source: main/waeup.kofa/trunk/docs/source/developerdocs/developernotes.rst @ 17898

Developer Notes
***************

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

The new WAeUP.Kofa is based on `Grok <http://grok.zope.org/>`_.

Installing a developer copy
===========================

See :ref:`installing_linux`

Documentation
=============

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

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

Building documentation
----------------------

See :ref:`building_documentation`

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 :mod:`waeup.kofa`
package for examples.

Testing
=======

Tests are most important to the reliability of the :mod:`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 :mod:`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.