source: main/waeup.ikoba/trunk/docs/source/developerdocs/developernotes.rst @ 15505

Last change on this file since 15505 was 11949, checked in by Henrik Bettermann, 10 years ago

Change of name.

File size: 4.1 KB
Line 
1Developer Notes
2***************
3
4How to setup a developer instance of the WAeUP.Ikoba, handle tests, docs
5etc.
6
7The new WAeUP.Ikoba is based on `Grok <http://grok.zope.org/>`_.
8
9Installing a developer copy
10===========================
11
12See :ref:`installing_linux`
13
14Documentation
15=============
16
17With the :mod:`waeup.ikoba` package we try to reach high standards in
18both, documentation and testing.
19
20:mod:`waeup.ikoba` makes extensive use of doctests, which this way also
21become both: executable (i.e. testable) examples and documentation.
22
23Building documentation
24----------------------
25
26See :ref:`building_documentation`
27
28Writing documentation
29---------------------
30
31means explaining to other developers what your code does and test it
32at the same time. See the many .txt files in the :mod:`waeup.ikoba`
33package for examples.
34
35Testing
36=======
37
38Tests are most important to the reliability of the :mod:`waeup.ikoba`
39package. We don't tell someone that our code works, if we cannot prove
40it. And we prove it by testing.
41
42Running tests
43-------------
44
45You can run all the tests for the package by doing::
46
47  $ bin/test
48
49If you like colored output (can improve readability of failure
50messages), use the ``-c`` switch::
51
52  $ bin/test -c
53
54We have many tests in the :mod:`waeup.ikoba` package so that sometimes
55you only want the functional *or* the unit tests to run. This can be
56done like this::
57
58  $ bin/test -c -u
59
60if you want only unit tests or like this::
61
62  $ bin/test -c -f
63
64if you only want functional tests.
65
66
67Writing tests
68-------------
69
70Is a wiiide topic. For now, please see the numerous .txt files in the
71source. Most of the **are** tests.
72
73Generally, we use `z3c.testsetup` for finding and setting up tests.
74
75There are mainly two kinds of tests we use:
76
77* unit- or simple doctests
78
79  These are included in test runs automatically, if they provide a
80  marker like this somewhere (normally near top of file)::
81
82    .. :doctest:
83
84  Most unit tests furthermore declare that they want to be run inside
85  the `WAeUPIkobaUnitTestLayer` defined in `waeup.ikoba.testing`. This
86  layer groks the whole `waeup.ikoba` package, so that all ZCA
87  components are already setup when you start your tests.
88 
89  To declare that a unit test testfile should be run inside this
90  layer, the testfile has to provide the following line::
91
92    .. :layer: waeup.ikoba.testing.WAeUPIkobaUnitTestLayer
93
94  Use it, if in your tests you make use of registered components like
95  utilities, adapters and the like.
96
97* integration or functional tests
98
99  These provide a full-blown ZODB storage, so that we can emulate
100  browser requests to the whole system. Functional tests are much more
101  expensive in terms of memory and runtime but needed, if you want to
102  test UI components.
103
104  A testfile is registered as functional test on testruns when it
105  provides a line like the following::
106
107    :Test-Layer: functional
108
109
110Code coverage
111-------------
112
113We want to make sure, that all aspects of our software are
114tested. This means, that all parts of the codes should be tested
115somewhere.
116
117To tell how good our test coverage is, we can also use the testrunner
118(``bin/test``)::
119
120  $ bin/test --coverage=coverage
121
122will run the tests but also look, which parts of code were touched by
123them. For releases we want 100% coverage. Beware: running tests with
124the ``--coverage`` switch slows down tests by factor 10 or more.
125
126The command above will output a table with percentages. Furthermore,
127in ``/parts/test/coverage`` you will (after the testrun) find your
128sources preceeded by markers which tell, how often (or none) a certain
129line was used in tests.
130
131To have a more convenient cmdline interface, we also provide some
132shortcuts::
133
134  $ bin/coverage-detect
135
136will run all the tests as shown above and put the results in
137``parts/coverage-detect/coverage``.
138
139After that you can run::
140
141  $ bin/coveragereport
142
143to get a browsable HTML representation of test coverage in
144``coverage-report/`` subdir.
145
146Both, the coverage reports and HTML documentation generated by sphinx
147can be packed and put onto a website as-is.
148
149It is also possible to generate the docs and reports nightly by a
150buildbot or something like this.
Note: See TracBrowser for help on using the repository browser.