36d1d1ac68
- Updated tox envlist, so just running `tox` from the CLI will now run all voting gate tests - Reduce duplicated definitions and commands - Remove any reliance on run_tests within tox - Removes all doc references to run_tests.sh, and replaces them with their tox equivalent. Where necessary, language around the tox commands has been altered or extended so that it makes sense and is consistent with other parts of the docs. Also adds a new "Test Environment" list to the docs, so that newcomers do not have to piece together CLI commands and their cryptic extensions from tox.ini - Move the inline shell scripting to its own file. Also fixes a bug when passing args, since the logic assumed you were attempting a subset test run (try `tox -e py27 -- --pdb` on master to compare) - Moved translation tooling from run_tests to manage.py, w/ help text and arg restrictions. This is much more flexible so that plugins can use it without having to copy commands, but still defaults to exactly the same parameters/behaviour from run_tests. Docs updated appropriately. - Removed npm/karma strange reliance on either .venv or tox/py27. Now it only uses tox/npm. Change-Id: I883f885bd424955d39ddcfde5ba396a88cfc041e Implements: blueprint enhance-tox Closes-Bug: 1638672
148 lines
4.3 KiB
ReStructuredText
148 lines
4.3 KiB
ReStructuredText
=======================
|
|
Horizon's tests and you
|
|
=======================
|
|
|
|
How to run the tests
|
|
====================
|
|
|
|
Because Horizon is composed of both the ``horizon`` app and the
|
|
``openstack_dashboard`` reference project, there are in fact two sets of unit
|
|
tests. While they can be run individually without problem, there is an easier
|
|
way:
|
|
|
|
Included at the root of the repository is the ``tox.ini`` config
|
|
which invokes both sets of tests, and optionally generates analyses on both
|
|
components in the process. ``tox`` is what Jenkins uses to verify the
|
|
stability of the project, so you should make sure you run it and it passes
|
|
before you submit any pull requests/patches.
|
|
|
|
To run all tests::
|
|
|
|
$ tox
|
|
|
|
It's also possible to run a subset of the tests. Open ``tox.ini`` in the
|
|
Horizon root directory to see a list of test environments. You can read more
|
|
about tox in general at https://tox.readthedocs.io/en/latest/.
|
|
|
|
By default running the Selenium tests will open your Firefox browser (you have
|
|
to install it first, else an error is raised), and you will be able to see the
|
|
tests actions::
|
|
|
|
$ tox -e selenium-headless
|
|
|
|
If you want to run the suite headless, without being able to see them (as they
|
|
are ran on Jenkins), you can run the tests::
|
|
|
|
$ tox -e selenium-headless
|
|
|
|
Selenium will use a virtual display in this case, instead of your own. In order
|
|
to run the tests this way you have to install the dependency `xvfb`, like
|
|
this::
|
|
|
|
$ sudo apt-get install xvfb
|
|
|
|
for a Debian OS flavour, or for Fedora/Red Hat flavours::
|
|
|
|
$ sudo yum install xorg-x11-server-Xvfb
|
|
|
|
If you can't run a virtual display, or would prefer not to, you can use the
|
|
PhantomJS web driver instead::
|
|
|
|
$ tox -e selenium-phantomjs
|
|
|
|
If you need to install PhantomJS, you may do so with `npm` like this::
|
|
|
|
$ npm -g install phantomjs
|
|
|
|
Alternatively, many distributions have system packages for phantomjs, or
|
|
it can be downloaded from http://phantomjs.org/download.html.
|
|
|
|
tox Test Environments
|
|
=====================
|
|
|
|
This is a list of test environments available to be executed by
|
|
``tox -e <name>``.
|
|
|
|
pep8
|
|
----
|
|
|
|
Runs pep8, which is a tool that checks Python code style. You can read more
|
|
about pep8 at https://www.python.org/dev/peps/pep-0008/
|
|
|
|
py27dj18, py27dj19, py27dj110
|
|
-----------------------------
|
|
|
|
Runs the Python unit tests against Django 1.8, Django 1.9 and Django 1.10
|
|
respectively
|
|
|
|
All other dependencies are as defined by the upper-constraints file at
|
|
https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt
|
|
|
|
You can run a subset of the tests by passing the test path as an argument to
|
|
tox::
|
|
|
|
$ tox -e py27dj18 -- openstack_dashboard.dashboards.identity.users.tests
|
|
|
|
You can also pass other arguments. For example, to drop into a live debugger
|
|
when a test fails you can use::
|
|
|
|
$ tox -e py27dj18 -- --pdb
|
|
|
|
py34
|
|
----
|
|
|
|
Runs the Python unit tests with a Python 3.4 environment.
|
|
|
|
py35
|
|
----
|
|
|
|
Runs the Python unit tests with a Python 3.5 environment.
|
|
|
|
releasenotes
|
|
------------
|
|
|
|
Outputs Horizons release notes as HTML to ``releasenotes/build/html``.
|
|
|
|
Also takes an alternative builder as an optional argument, such as
|
|
``tox -e docs -- <builder>``, which will output to
|
|
``releasenotes/build/<builder>``. Available builders are listed at
|
|
http://www.sphinx-doc.org/en/latest/builders.html
|
|
|
|
npm
|
|
---
|
|
|
|
Installs the npm dependencies listed in ``package.json`` and runs the
|
|
JavaScript tests. Can also take optional arguments, which will be executed
|
|
as an npm script following the dependency install, instead of ``test``.
|
|
|
|
Example::
|
|
|
|
$ tox -e npm -- lintq
|
|
|
|
docs
|
|
----
|
|
|
|
Outputs Horizons documentation as HTML to ``doc/build/html``.
|
|
|
|
Also takes an alternative builder as an optional argument, such as
|
|
``tox -e docs -- <builder>``, which will output to ``doc/build/<builder>``.
|
|
Available builders are listed at
|
|
http://www.sphinx-doc.org/en/latest/builders.html
|
|
|
|
Example::
|
|
|
|
$ tox -e docs -- latexpdf
|
|
|
|
Writing tests
|
|
=============
|
|
|
|
Horizon uses Django's unit test machinery (which extends Python's ``unittest2``
|
|
library) as the core of its test suite. As such, all tests for the Python code
|
|
should be written as unit tests. No doctests please.
|
|
|
|
In general new code without unit tests will not be accepted, and every bugfix
|
|
*must* include a regression test.
|
|
|
|
For a much more in-depth discussion of testing, see the :doc:`testing topic
|
|
guide </topics/testing>`.
|