Developing Obviel

Here is some information on how we develop Obviel and how you could participate.

Please talk to us our on our mailing list about your plans!

Sources

Obviel’s source code is maintained on bitbucket: http://bitbucket.org/obviel/obviel

You can check it out using Mercurial (hg); see the bitbucket documentation for more information as well.

Feel free to fork Obviel on bitbucket if you want to hack on it, and send us a pull request when you want us to merge your improvements.

Running the tests

The Obviel tests run in a web browser.

Accessing the tests

You can access Obviel’s tests by constructing a file: URL to the test page. For instance:

file:///home/faassen/projects/obviel/src/test/index.html

You can also access Obviel’s tests through a web server. This is useful as some web browsers have test failures due to the peculiar way file: URLs are accessed. In addition, the JSCoverage tool described below recommends against the use of file: URLs. A simple way to start a web server is to type this in the project directory:

$ python -m SimpleHTTPServer

where python is a Python 2.x interpreter. You can then navigate to:

http://localhost:8000/src/test

for the test page.

Executing the tests

From the test page, you will see various links to the individual test suites:

  • obviel.js tests - tests for the Obviel core
  • obviel-forms.js tests - tests for Obviel forms
  • JSHint - run JSHint against Obviel

There is also a section with manual (non-automatic) tests; this is more for experimentation during development with the form logic in particular.

Modifying the tests

The tests are maintained in the test directory under the src directory. They use qunit test engine.

Test coverage

The JSCoverage tool can be used to analyze the test coverage: how much of the Obviel code is being actually called from the test suite. To use it, first create a special coverage-analysis copy of the Obviel project directory. If your Obviel project directory is called obviel, change to the parent directory above it and type this:

$ jscoverage obviel obviel-cov

Then go to obviel-cov and start a web server:

$ python -m SimpleHTTPServer

Now go to the special coverage analysis page:

http://localhost:8000/jscoverage.html

In the URL input on the coverage page, type the following and press Open in frame:

http://localhost:8000/src/test

Then click on the automatic test suite you want to run.

You can then click on the ‘Summary’ tab and see how much coverage the test suite has for the file src/obviel.js.

Building the documentation

Obviel’s documentation is written using restructured text and Sphinx.

To build the documentation of Obviel you need Python 2.6 or Python 2.7. First you need to install buildout, a tool that installs some useful scripts for us. In the Obviel project directory, type the following:

$ python bootstrap.py -d
$ bin/buildout

After you’ve done this once, you can build the documentation using Sphinx:

$ bin/sphinxbuilder

The docs source is in doc, the built documentation will be available in doc/_build/html.

Note that the src directory in its entirety is also copied into the documentation tree under _static. This is done to make it easy to publish demo code as part of the website.

Obviel test server

We’ve included obvielts, which is a simple Python-based web server that is used to test integration with dynamic server code.

To build obvielts, you need to do a buildout (if you’ve installed the documentation you already will have it):

$ python bootstrap.py -d
$ bin/buildout

You can now start the obvielts server using paster:

$ bin/paster serve parts/etc/debug.ini

It will be available here:

http://localhost:8080

The code is in py/obvielts. It makes use of Obviel’s Fanstatic integration, which is in py/js.obviel.