From a6fdab04328102041cc851bf66667bf5a5e55a46 Mon Sep 17 00:00:00 2001
From: Pavlo Shchelokovskyy <pshchelokovskyy@mirantis.com>
Date: Thu, 11 Dec 2014 14:20:36 +0200
Subject: [PATCH] Update testing-overview.txt

- update for actual tests directory structure used
- describe how to use tox to run only a subset of tests
- add hint on how to run tests when debuggers are used
- also remove non-existent heat/testing/README.rst from MANINFEST.in

Change-Id: I1441f79a006a4dfba2d7ee54ca6f4f7577205c0d
---
 MANIFEST.in                     |  1 -
 heat/tests/testing-overview.txt | 42 ++++++++++++++++++++++-----------
 2 files changed, 28 insertions(+), 15 deletions(-)

diff --git a/MANIFEST.in b/MANIFEST.in
index 0dd4ae65b..a14c6d57c 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -14,7 +14,6 @@ include heat/cloudinit/part-handler.py
 include heat/db/sqlalchemy/migrate_repo/migrate.cfg
 include heat/db/sqlalchemy/migrate_repo/README
 include heat/openstack/common/README
-include heat/testing/README.rst
 include heat/tests/examples/tags.txt
 include heat/tests/testing-overview.txt
 include heat/tests/v1_1/testfile.txt
diff --git a/heat/tests/testing-overview.txt b/heat/tests/testing-overview.txt
index 8ae724f24..22a8a5e6d 100644
--- a/heat/tests/testing-overview.txt
+++ b/heat/tests/testing-overview.txt
@@ -1,23 +1,20 @@
 Heat testing
 ------------
 
-All tests are to be placed in the heat/tests directory. The directory
-is organized by test type (unit, functional, etc). Within each type
-directory one may create another directory for additional test files as
-well as a separate __init__.py, which should be blank.
+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
-|-- examples
+|-- autoscaling
 |   |-- __init__.py
 |   |-- test1.py
 |   |-- test2.py
 |   |-- test3.py
 |-- __init__.py
-`-- unit
-    |-- __init__.py
-    |-- test_template_convert.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
@@ -30,19 +27,36 @@ 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
-tools/test-requires file needs to be updated so that the virtual
+test-requirements.txt file needs to be updated so that the virtual
 environment will be able to successfully execute all tests.
 
 Running the tests
 -----------------
 
-During development, the simplest way to run tests is to simply invoke
-testr directly.
+Advised way of running tests is the same as in OpenStack testing
+infrastructure, that is using tox.
 
-$ testr run
+$ tox
 
-To run the tests with a clean virtual env in the same manner as the
-OpenStack testing infrastructure does so, use 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