Heat testing
------------

All unit tests are to be placed in the heat/tests directory,
and tests might be organized by tested subsystem. Each subsystem directory
must contain a separate blank __init__.py for tests discovery to function.

An example directory structure illustrating the above:

heat/tests
|-- autoscaling
|   |-- __init__.py
|   |-- test1.py
|   |-- test2.py
|   |-- test3.py
|-- __init__.py
|-- test_template_convert.py

If a given test has no overlapping requirements (variables or same
routines) a new test does not need to create a subdirectory under the
test type.

Implementing a test
-------------------

Testrepository - http://pypi.python.org/pypi/testrepository is used to
find and run tests, parallelize their runs, and record timing/results.

If new dependencies are introduced upon the development of a test, the
test-requirements.txt file needs to be updated so that the virtual
environment will be able to successfully execute all tests.

Running the tests
-----------------

Advised way of running tests is the same as in OpenStack testing
infrastructure, that is using tox.

$ tox

This by default will run unit tests suite with Python 2.7 and PEP8/HACKING
style checks. To run only one type of tests you can explicitly provide tox
with the test environment to use.

$ tox -epy27 # test suite on python 2.7
$ tox -epep8 # run full source code checker

To run only a subset of tests, you can provide tox with a regex argument
defining which tests to execute.

$ tox -epy27 -- VolumeTests

To use debugger like pdb during test run, one has to run tests directly
with other, non-concurrent test runner instead of testr.
That also presumes that you have a virtual env with all heat dependencies active.
Below is an example bash script using testtools test runner that also allows
running single tests by providing a regex.

#! /usr/bin/env sh
testlist=$(mktemp)
testr list-tests "$1" > $testlist
python -m testtools.run --load-list $testlist

Another way to use debugger for testing is run tox with command:
$ tox -e debug -- heat.tests.test_stack.StackTest.test_stack_reads_tenant

Note: last approach is mostly useful to run single tests.