1
====================================
2
Organizing Test Fixtures into Layers
3
====================================
9
Layers allow more flexible organization of test fixtures than test-,
10
class- and module- level fixtures. Layers in nose2 are inspired by
11
and aim to be compatible with the layers used by Zope's testrunner.
13
Using layers, you can do things like:
15
* Implement package-level fixtures by sharing a layer among all
16
test cases in the package.
18
* Share fixtures across tests in different modules without
19
having them run multiple times.
21
* Create a fixture tree deeper than three levels (test, class and
24
* Make fixtures available for other packages or projects to use.
26
A layer is a *new-style* class that implements at least a ``setUp``
29
.. code-block :: python
36
It may also implement ``tearDown``, ``testSetUp`` and
37
``testTearDown``, all as classmethods.
39
To assign a layer to a test case, set the test case's ``layer``
42
class Test(unittest.TestCase):
45
Note that the layer *class* is assigned, not an instance of the
46
layer. Typically layer classes are not instantiated.
51
Layers may subclass other layers:
53
.. code-block :: python
55
class SubLayer(Layer):
60
In this case, all tests that belong to the sub-layer also belong to
61
the base layer. For example for this test case::
63
class SubTest(unittest.TestCase):
66
The ``setUp`` methods from *both* ``SubLayer`` and ``Layer`` will run
67
before any tests are run. The superclass's setup will always run
68
before the subclass's setup. For teardown, the reverse: the subclass's
69
teardown runs before the superclass's.
73
One important thing to note: layers that subclass other layers *must
74
not* call their superclass's ``setUp``, ``tearDown``, etc. -- the test
75
runner will take care of organizing tests so that the superclass's
76
methods are called in the right order::
85
SubLayer.testTearDown <-
90
If a sublayer calls it superclass's methods directly, *those
91
methods will be called twice*.
94
Layer method reference
95
======================
99
Not an actual class, but reference documentation for
100
the methods layers can implement. There is no layer
101
base class. Layers must be subclasses of :class:`object`
104
.. classmethod :: setUp(cls)
106
The layer's ``setUp`` method is called before any tests belonging to
107
that layer are executed. If no tests belong to the layer (or one of
108
its sub-layers) then the ``setUp`` method will not
111
.. classmethod :: tearDown(cls)
113
The layer's ``tearDown`` method is called after any tests
114
belonging to the layer are executed, if the layer's ``setUp``
115
method was called and did not raise an exception. It will not
116
be called if the layer has no ``setUp`` method, or if that
117
method did not run or did raise an exception.
119
.. classmethod :: testSetUp(cls[, test])
121
The layer's ``testSetUp`` method is called before each test
122
belonging to the layer (and its sub-layers). If
123
the method is defined to accept an argument, the test case
124
instance is passed to the method. The method may also be
125
defined to take no arguments.
127
.. classmethod :: testTearDown(cls[, test])
129
The layer's ``testTearDown`` method is called after each test
130
belonging to the layer (and its sub-layers), if
131
the layer also defines a ``setUpTest`` method and that method
132
ran successfully (did not raise an exception) for this test
138
nose2 includes a DSL for setting up layer-using tests called
139
"such". Read all about it here: :doc:`../such_dsl`.
144
The layers plugin module includes a second plugin that alters test
145
report output to make the layer groupings more clear. When activated
146
with the :option:`--layer-reporter` command-line option (or via a config
147
file), test output that normally looks like this::
149
test (test_layers.NoLayer) ... ok
150
test (test_layers.Outer) ... ok
151
test (test_layers.InnerD) ... ok
152
test (test_layers.InnerA) ... ok
153
test (test_layers.InnerA_1) ... ok
154
test (test_layers.InnerB_1) ... ok
155
test (test_layers.InnerC) ... ok
156
test2 (test_layers.InnerC) ... ok
158
----------------------------------------------------------------------
159
Ran 8 tests in 0.001s
163
Will instead look like this::
165
test (test_layers.NoLayer) ... ok
167
test (test_layers.Outer) ... ok
169
test (test_layers.InnerD) ... ok
171
test (test_layers.InnerA) ... ok
174
test (test_layers.InnerC) ... ok
175
test2 (test_layers.InnerC) ... ok
177
test (test_layers.InnerB_1) ... ok
179
test (test_layers.InnerA_1) ... ok
181
----------------------------------------------------------------------
182
Ran 8 tests in 0.002s
186
The layer reporter plugin can also optionally colorize the keywords
187
('A', 'having', and 'should' by default) in output from tests defined
188
with the :doc:`such DSL <../such_dsl>`.
190
If you would like to change how the layer is displayed you need to set the description attribute.
192
.. code-block :: python
195
description = '*** This is a very important custom layer description ***'
197
Now the output will be the following::
200
test (test_layers.NoLayer) ... ok
202
test (test_layers.Outer) ... ok
203
*** This is a very important custom layer description ***
204
test (test_layers.InnerD) ... ok
206
test (test_layers.InnerA) ... ok
209
test (test_layers.InnerC) ... ok
210
test2 (test_layers.InnerC) ... ok
212
test (test_layers.InnerB_1) ... ok
214
test (test_layers.InnerA_1) ... ok
216
----------------------------------------------------------------------
217
Ran 8 tests in 0.002s
225
Test case order and module isolation
226
------------------------------------
228
Test cases that use layers will not execute in the same order as test
229
cases that do not. In order to execute the layers efficiently, the
230
test runner must reorganize *all* tests in the loaded test suite to
231
group those having like layers together (and sub-layers under their
232
parents). If you share layers across modules this may result in tests
233
from one module executing interleaved with tests from a different
237
Mixing layers with setUpClass and module fixtures
238
-------------------------------------------------
240
**Don't cross the streams.**
242
The implementation of class- and module-level fixtures in unittest2
243
depends on introspecting the class hierarchy inside of the
244
unittest.TestSuite. Since the suites that the layers plugin uses to
245
organize tests derive from :class:`unittest.BaseTestSuite` not
246
:class:`unittest.TestSuite`, class- and module- level fixtures in
247
TestCase classes that use layers will be ignored.
249
Mixing layers and multiprocess testing
250
--------------------------------------
252
In the initial release, *test suites using layers are incompatible with
253
the multiprocess plugin*. This should be fixed in a future release.
259
.. autoplugin :: nose2.plugins.layers
added
removed
docs/plugins/layers.rst
