2 Licensed under the Apache License, Version 2.0 (the "License"); you may
3 not use this file except in compliance with the License. You may obtain
4 a copy of the License at
6 http://www.apache.org/licenses/LICENSE-2.0
8 Unless required by applicable law or agreed to in writing, software
9 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
10 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
11 License for the specific language governing permissions and limitations
15 Convention for heading levels in Neutron devref:
16 ======= Heading 0 (reserved for the title in a document)
21 (Avoid deeper levels because they do not render well.)
30 Neutron relies on unit, functional, fullstack and API tests to ensure its
31 quality, as described below. In addition to in-tree testing, `Tempest`_ is
32 responsible for validating Neutron's integration with other OpenStack
33 components via scenario tests, and `Rally`_ is responsible for benchmarking.
35 .. _Tempest: http://docs.openstack.org/developer/tempest/
36 .. _Rally: http://rally.readthedocs.org/en/latest/
41 Unit tests (neutron/test/unit/) are meant to cover as much code as
42 possible. They are designed to test the various pieces of the Neutron tree to
43 make sure any new changes don't break existing functionality. Unit tests have
44 no requirements nor make changes to the system they are running on. They use
45 an in-memory sqlite database to test DB interaction.
50 Functional tests (neutron/tests/functional/) are intended to
51 validate actual system interaction. Mocks should be used sparingly,
52 if at all. Care should be taken to ensure that existing system
53 resources are not modified and that resources created in tests are
54 properly cleaned up both on test success and failure.
59 Fullstack tests (neutron/tests/fullstack/) target Neutron as a whole.
60 The test infrastructure itself manages the Neutron server and its agents.
61 Fullstack tests are a form of integration testing and fill a void between
62 unit/functional tests and Tempest. More information may be found
63 `here. <fullstack_testing.html>`_
68 API tests (neutron/tests/api/) are intended to ensure the function
69 and stability of the Neutron API. As much as possible, changes to
70 this path should not be made at the same time as changes to the code
71 to limit the potential for introducing backwards-incompatible changes,
72 although the same patch that introduces a new API should include an API
75 Since API tests target a deployed Neutron daemon that is not test-managed,
76 they should not depend on controlling the runtime configuration
77 of the target daemon. API tests should be black-box - no assumptions should
78 be made about implementation. Only the contract defined by Neutron's REST API
79 should be validated, and all interaction with the daemon should be via
82 neutron/tests/api was copied from the Tempest project. The Tempest networking
83 API directory was frozen and any new tests belong to the Neutron repository.
88 It is expected that any new changes that are proposed for merge
89 come with tests for that feature or code area. Ideally any bugs
90 fixes that are submitted also have tests to prove that they stay
91 fixed! In addition, before proposing for merge, all of the
92 current tests should be passing.
94 Structure of the Unit Test Tree
95 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97 The structure of the unit test tree should match the structure of the
100 - target module: neutron.agent.utils
102 - test module: neutron.tests.unit.agent.test_utils
104 Unit test modules should have the same path under neutron/tests/unit/
105 as the module they target has under neutron/, and their name should be
106 the name of the target module prefixed by `test_`. This requirement
107 is intended to make it easier for developers to find the unit tests
110 Similarly, when a test module targets a package, that module's name
111 should be the name of the package prefixed by `test_` with the same
112 path as when a test targets a module, e.g. ::
114 - target package: neutron.ipam
116 - test module: neutron.tests.unit.test_ipam
118 The following command can be used to validate whether the unit test
119 tree is structured according to the above requirements: ::
121 ./tools/check_unit_test_structure.sh
123 Where appropriate, exceptions can be added to the above script. If
124 code is not part of the Neutron namespace, for example, it's probably
125 reasonable to exclude their unit tests from the check.
130 There are three mechanisms for running tests: run_tests.sh, tox,
131 and nose2. Before submitting a patch for review you should always
132 ensure all test pass; a tox run is triggered by the jenkins gate
133 executed on gerrit for each patch pushed for review.
135 With these mechanisms you can either run the tests in the standard
136 environment or create a virtual environment to run them in.
138 By default after running all of the tests, any pep8 errors
139 found in the tree will be reported.
145 You can use the `run_tests.sh` script in the root source directory to execute
146 tests in a virtualenv::
154 You can use `nose2`_ to run individual tests, as well as use for debugging
155 portions of your code::
157 source .venv/bin/activate
161 There are disadvantages to running nose2 - the tests are run sequentially, so
162 race condition bugs will not be triggered, and the full test suite will
163 take significantly longer than tox & testr. The upside is that testr has
164 some rough edges when it comes to diagnosing errors and failures, and there is
165 no easy way to set a breakpoint in the Neutron code, and enter an
166 interactive debugging session while using testr.
168 Note that nose2's predecessor, `nose`_, does not understand
169 `load_tests protocol`_ introduced in Python 2.7. This limitation will result in
170 errors being reported for modules that depend on load_tests
171 (usually due to use of `testscenarios`_). nose, therefore, is not supported,
174 .. _nose2: http://nose2.readthedocs.org/en/latest/index.html
175 .. _nose: https://nose.readthedocs.org/en/latest/index.html
176 .. _load_tests protocol: https://docs.python.org/2/library/unittest.html#load-tests-protocol
177 .. _testscenarios: https://pypi.python.org/pypi/testscenarios/
182 Neutron, like other OpenStack projects, uses `tox`_ for managing the virtual
183 environments for running test cases. It uses `Testr`_ for managing the running
186 Tox handles the creation of a series of `virtualenvs`_ that target specific
189 Testr handles the parallel execution of series of test cases as well as
190 the tracking of long-running tests and other things.
192 For more information on the standard Tox-based test infrastructure used by
193 OpenStack and how to do some common test/debugging procedures with Testr,
196 https://wiki.openstack.org/wiki/Testr
198 .. _Testr: https://wiki.openstack.org/wiki/Testr
199 .. _tox: http://tox.readthedocs.org/en/latest/
200 .. _virtualenvs: https://pypi.python.org/pypi/virtualenv
205 Running pep8 and unit tests is as easy as executing this in the root
206 directory of the Neutron source code::
214 Since pep8 includes running pylint on all files, it can take quite some time to run.
215 To restrict the pylint check to only the files altered by the latest patch changes::
219 To run only the unit tests::
226 To run functional tests that do not require sudo privileges or
227 specific-system dependencies::
231 To run all the functional tests, including those requiring sudo
232 privileges and system-specific dependencies, the procedure defined by
233 tools/configure_for_func_testing.sh should be followed.
235 IMPORTANT: configure_for_func_testing.sh relies on DevStack to perform
236 extensive modification to the underlying host. Execution of the
237 script requires sudo privileges and it is recommended that the
238 following commands be invoked only on a clean and disposeable VM.
239 A VM that has had DevStack previously installed on it is also fine. ::
241 git clone https://git.openstack.org/openstack-dev/devstack ../devstack
242 ./tools/configure_for_func_testing.sh ../devstack -i
243 tox -e dsvm-functional
245 The '-i' option is optional and instructs the script to use DevStack
246 to install and configure all of Neutron's package dependencies. It is
247 not necessary to provide this option if DevStack has already been used
248 to deploy Neutron to the target host.
253 To run all the full-stack tests, you may use: ::
255 tox -e dsvm-fullstack
257 Since full-stack tests often require the same resources and
258 dependencies as the functional tests, using the configuration script
259 tools/configure_for_func_testing.sh is advised (As described above).
260 When running full-stack tests on a clean VM for the first time, we
261 advise to run ./stack.sh successfully to make sure all Neutron's
262 dependencies are met. Full-stack based Neutron daemons produce logs to a
263 sub-folder in /tmp/fullstack-logs (for example, a test named
264 "test_example" will produce logs to /tmp/fullstack-logs/test_example/),
265 so that will be a good place to look if your test is failing.
270 To run the api tests, deploy Tempest and Neutron with DevStack and
271 then run the following command: ::
275 If tempest.conf cannot be found at the default location used by
276 DevStack (/opt/stack/tempest/etc) it may be necessary to set
277 TEMPEST_CONFIG_DIR before invoking tox: ::
279 export TEMPEST_CONFIG_DIR=[path to dir containing tempest.conf]
283 Running Individual Tests
284 ~~~~~~~~~~~~~~~~~~~~~~~~
286 For running individual test modules, cases or tests, you just need to pass
287 the dot-separated path you want as an argument to it.
289 For example, the following would run only a single test or test case::
291 $ ./run_tests.sh neutron.tests.unit.test_manager
292 $ ./run_tests.sh neutron.tests.unit.test_manager.NeutronManagerTestCase
293 $ ./run_tests.sh neutron.tests.unit.test_manager.NeutronManagerTestCase.test_service_plugin_is_loaded
297 $ tox -e py27 neutron.tests.unit.test_manager
298 $ tox -e py27 neutron.tests.unit.test_manager.NeutronManagerTestCase
299 $ tox -e py27 neutron.tests.unit.test_manager.NeutronManagerTestCase.test_service_plugin_is_loaded
304 Neutron has a fast growing code base and there are plenty of areas that
305 need better coverage.
307 To get a grasp of the areas where tests are needed, you can check
308 current unit tests coverage by running::
316 Since the coverage command can only show unit test coverage, a coverage
317 document is maintained that shows test coverage per area of code in:
318 doc/source/devref/testing_coverage.rst. You could also rely on Zuul
319 logs, that are generated post-merge (not every project builds coverage
320 results). To access them, do the following:
322 * Check out the latest `merge commit <https://review.openstack.org/gitweb?p=openstack/neutron.git;a=search;s=Jenkins;st=author>`_
323 * Go to: http://logs.openstack.org/<first-2-digits-of-sha1>/<sha1>/post/neutron-coverage/.
324 * `Spec <https://review.openstack.org/#/c/221494/>`_ is a work in progress to
325 provide a better landing page.
330 By default, calls to pdb.set_trace() will be ignored when tests
331 are run. For pdb statements to work, invoke run_tests as follows::
333 $ ./run_tests.sh -d [test module path]
335 It's possible to debug tests in a tox environment::
337 $ tox -e venv -- python -m testtools.run [test module path]
339 Tox-created virtual environments (venv's) can also be activated
340 after a tox run and reused for debugging::
343 $ . .tox/venv/bin/activate
344 $ python -m testtools.run [test module path]
346 Tox packages and installs the Neutron source tree in a given venv
347 on every invocation, but if modifications need to be made between
348 invocation (e.g. adding more pdb statements), it is recommended
349 that the source tree be installed in the venv in editable mode::
351 # run this only after activating the venv
352 $ pip install --editable .
354 Editable mode ensures that changes made to the source tree are
355 automatically reflected in the venv, and that such changes are not
356 overwritten during the next tox run.
358 Post-mortem Debugging
359 ~~~~~~~~~~~~~~~~~~~~~
361 Setting OS_POST_MORTEM_DEBUGGER in the shell environment will ensure
362 that the debugger .post_mortem() method will be invoked on test failure::
364 $ OS_POST_MORTEM_DEBUGGER=pdb ./run_tests.sh -d [test module path]
366 Supported debuggers are pdb, and pudb. Pudb is full-screen, console-based
367 visual debugger for Python which let you inspect variables, the stack,
368 and breakpoints in a very visual way, keeping a high degree of compatibility
371 $ ./.venv/bin/pip install pudb
373 $ OS_POST_MORTEM_DEBUGGER=pudb ./run_tests.sh -d [test module path]
378 .. [#pudb] PUDB debugger:
379 https://pypi.python.org/pypi/pudb