73a31e7adf
an changed to "a" sqlite to SQLite text plural changed Change-Id: I76aa0ddcca02a1c2cbe2eceec5469d4d57bf9f89
149 lines
6.3 KiB
XML
149 lines
6.3 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
version="5.0"
|
|
xml:id="unit_tests">
|
|
<title>Unit_Tests</title>
|
|
<section xml:id="header">
|
|
<title>Header</title>
|
|
<para>
|
|
</para>
|
|
</section>
|
|
<section xml:id="Unit-Tests">
|
|
<title>Unit-Tests</title>
|
|
<para>
|
|
==========
|
|
Cinder contains a suite of unit tests, in the cinder/tests directory.
|
|
Any proposed code change will be automatically rejected by the OpenStack
|
|
Jenkins server [#f1]_ if the change causes unit test failures.
|
|
</para>
|
|
</section>
|
|
<section xml:id="Running-the-tests">
|
|
<title>Running-The-Tests</title>
|
|
<para>
|
|
-----------------
|
|
Run the unit tests by doing::
|
|
./run_tests.sh
|
|
This script is a wrapper around the `nose`_ testrunner and the `pep8`_ checker.
|
|
.. _nose: http://code.google.com/p/python-nose/
|
|
.. _pep8: https://github.com/jcrocholl/pep8
|
|
Flags
|
|
-----
|
|
The ``run_tests.sh`` script supports several flags. You can view a list of
|
|
flags by doing::
|
|
run_tests.sh -h
|
|
This will show the following help information::
|
|
Usage: ./run_tests.sh [OPTION]...
|
|
Run Cinder's test suite(s)
|
|
-V, --virtual-env Always use virtualenv. Install automatically if not present
|
|
-N, --no-virtual-env Don't use virtualenv. Run tests in local environment
|
|
-s, --no-site-packages Isolate the virtualenv from the global Python environment
|
|
-r, --recreate-db Recreate the test database (deprecated, as this is now the default).
|
|
-n, --no-recreate-db Don't recreate the test database.
|
|
-x, --stop Stop running tests after the first error or failure.
|
|
-f, --force Force a clean re-build of the virtual environment. Useful when dependencies have been added.
|
|
-p, --pep8 Just run pep8
|
|
-P, --no-pep8 Don't run pep8
|
|
-c, --coverage Generate coverage report
|
|
-h, --help Print this usage message
|
|
--hide-elapsed Don't print the elapsed time for each test along with slow test list
|
|
Because ``run_tests.sh`` is a wrapper around nose, it also accepts the same
|
|
flags as nosetests. See the `nose options documentation`_ for details about
|
|
these additional flags.
|
|
.. _nose options documentation: http://readthedocs.org/docs/nose/en/latest/usage.html#options
|
|
</para>
|
|
</section>
|
|
<section xml:id="Running-a-subset-of-tests">
|
|
<title>Running-A-Subset-Of-Tests</title>
|
|
<para>
|
|
-------------------------
|
|
Instead of running all tests, you can specify an individual directory, file,
|
|
class, or method that contains test code.
|
|
To run the tests in the ``cinder/tests/scheduler`` directory::
|
|
./run_tests.sh scheduler
|
|
To run the tests in the ``cinder/tests/test_libvirt.py`` file::
|
|
./run_tests.sh test_libvirt
|
|
To run the tests in the `HostStateTestCase` class in
|
|
``cinder/tests/test_libvirt.py``::
|
|
./run_tests.sh test_libvirt:HostStateTestCase
|
|
To run the `ToPrimitiveTestCase.test_dict` test method in
|
|
``cinder/tests/test_utils.py``::
|
|
./run_tests.sh test_utils:ToPrimitiveTestCase.test_dict
|
|
</para>
|
|
</section>
|
|
<section xml:id="Suppressing-logging-output-when-tests-fail">
|
|
<title>Suppressing-Logging-Output-When-Tests-Fail</title>
|
|
<para>
|
|
------------------------------------------
|
|
By default, when one or more unit test fails, all of the data sent to the
|
|
logger during the failed tests will appear on standard output, which typically
|
|
consists of many lines of text. The logging output can make it difficult to
|
|
identify which specific tests have failed, unless your terminal has a large
|
|
scrollback buffer or you have redirected output to a file.
|
|
You can suppress the logging output by calling ``run_tests.sh`` with the nose
|
|
flag::
|
|
--nologcapture
|
|
</para>
|
|
</section>
|
|
<section xml:id="Virtualenv">
|
|
<title>Virtualenv</title>
|
|
<para>
|
|
----------
|
|
By default, the tests use the Python packages installed inside a
|
|
virtualenv [#f2]_. (This is equivalent to using the ``-V, --virtualenv`` flag).
|
|
If the virtualenv does not exist, it will be created the first time the tests are run.
|
|
If you wish to recreate the virtualenv, call ``run_tests.sh`` with the flag::
|
|
-f, --force
|
|
Recreating the virtualenv is useful if the package dependencies have changed
|
|
since the virtualenv was last created. If the ``requirements.txt`` or
|
|
``tools/install_venv.py`` files have changed, it's a good idea to recreate the
|
|
virtualenv.
|
|
By default, the unit tests will see both the packages in the virtualenv and
|
|
the packages that have been installed in the Python global environment. In
|
|
some cases, the packages in the Python global environment may cause a conflict
|
|
with the packages in the virtualenv. If this occurs, you can isolate the
|
|
virtualenv from the global environment by using the flag::
|
|
-s, --no-site packages
|
|
If you do not wish to use a virtualenv at all, use the flag::
|
|
-N, --no-virtual-env
|
|
</para>
|
|
</section>
|
|
<section xml:id="Database">
|
|
<title>Database</title>
|
|
<para>
|
|
--------
|
|
Some of the unit tests make queries against a SQLite database [#f3]_. By
|
|
default, the test database (``tests.sqlite``) is deleted and recreated each
|
|
time ``run_tests.sh`` is invoked (This is equivalent to using the
|
|
``-r, --recreate-db`` flag). To reduce testing time if a database already
|
|
exists it can be reused by using the flag::
|
|
-n, --no-recreate-db
|
|
Reusing an existing database may cause tests to fail if the schema has
|
|
changed. If any files in the ``cinder/db/sqlalchemy`` have changed, it's a good
|
|
idea to recreate the test database.
|
|
</para>
|
|
</section>
|
|
<section xml:id="Gotchas">
|
|
<title>Gotchas</title>
|
|
<para>
|
|
-------
|
|
<itemizedlist>
|
|
<listitem><para></para></listitem>
|
|
</itemizedlist>
|
|
If you are running the unit tests from a shared folder, you may see tests start
|
|
to fail or stop completely as a result of Python lockfile issues [#f4]_. You
|
|
can get around this by manually setting or updating the following line in
|
|
``cinder/tests/conf_fixture.py``::
|
|
CONF['lock_path'].SetDefault('/tmp')
|
|
Note that you may use any location (not just ``/tmp``!) as long as it is not
|
|
a shared folder.
|
|
.. rubric:: Footnotes
|
|
.. [#f1] See :doc:`jenkins`.
|
|
.. [#f2] See :doc:`development.environment` for more details about the use of
|
|
virtualenv.
|
|
.. [#f3] There is an effort underway to use a fake DB implementation for the
|
|
unit tests. See https://lists.launchpad.net/openstack/msg05604.html
|
|
</para>
|
|
</section>
|
|
</section> |