Developer Notes

How to setup a developer instance of the WAeUP.Kofa, handle tests, docs etc.

The new WAeUP.Kofa is based on Grok.

Installing a developer copy

See Installation of Kofa

Documentation

With the waeup.kofa package we try to reach high standards in both, documentation and testing.

waeup.kofa makes extensive use of doctests, which this way also become both: executable (i.e. testable) examples and documentation.

Building documentation

See Building Documentation (Linux OS only)

Writing documentation

means explaining to other developers what your code does and test it at the same time. See the many .txt files in the waeup.kofa package for examples.

Testing

Tests are most important to the reliability of the waeup.kofa package. We don’t tell someone that our code works, if we cannot prove it. And we prove it by testing.

Running tests

You can run all the tests for the package by doing:

$ bin/test

If you like colored output (can improve readability of failure messages), use the -c switch:

$ bin/test -c

We have many tests in the waeup.kofa package so that sometimes you only want the functional or the unit tests to run. This can be done like this:

$ bin/test -c -u

if you want only unit tests or like this:

$ bin/test -c -f

if you only want functional tests.

Writing tests

Is a wiiide topic. For now, please see the numerous .txt files in the source. Most of the are tests.

Generally, we use z3c.testsetup for finding and setting up tests.

There are mainly two kinds of tests we use:

• unit- or simple doctests

  These are included in test runs automatically, if they provide a marker like this somewhere (normally near top of file):

  .. :doctest:
  

  Most unit tests furthermore declare that they want to be run inside the WAeUPKofaUnitTestLayer defined in waeup.kofa.testing. This layer groks the whole waeup.kofa package, so that all ZCA components are already setup when you start your tests.

  To declare that a unit test testfile should be run inside this layer, the testfile has to provide the following line:

  .. :layer: waeup.kofa.testing.WAeUPKofaUnitTestLayer
  

  Use it, if in your tests you make use of registered components like utilities, adapters and the like.

• integration or functional tests

  These provide a full-blown ZODB storage, so that we can emulate browser requests to the whole system. Functional tests are much more expensive in terms of memory and runtime but needed, if you want to test UI components.

  A testfile is registered as functional test on testruns when it provides a line like the following:

  :Test-Layer: functional
  

Code coverage

We want to make sure, that all aspects of our software are tested. This means, that all parts of the codes should be tested somewhere.

To tell how good our test coverage is, we can also use the testrunner (bin/test):

$ bin/test --coverage=coverage

will run the tests but also look, which parts of code were touched by them. For releases we want 100% coverage. Beware: running tests with the --coverage switch slows down tests by factor 10 or more.

The command above will output a table with percentages. Furthermore, in /parts/test/coverage you will (after the testrun) find your sources preceeded by markers which tell, how often (or none) a certain line was used in tests.

To have a more convenient cmdline interface, we also provide some shortcuts:

$ bin/coverage-detect

will run all the tests as shown above and put the results in parts/coverage-detect/coverage.

After that you can run:

$ bin/coveragereport

to get a browsable HTML representation of test coverage in coverage-report/ subdir.

Both, the coverage reports and HTML documentation generated by sphinx can be packed and put onto a website as-is.

It is also possible to generate the docs and reports nightly by a buildbot or something like this.