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!


Obviel’s source code is maintained on bitbucket:

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:


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:


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:


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


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 -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.