From dd689f35929689d6c907848b375461cd44a5aa4d Mon Sep 17 00:00:00 2001
From: Ankur Gupta <ankur.gupta@intel.com>
Date: Mon, 28 Nov 2016 17:30:04 -0600
Subject: [PATCH] Introduce TESTING.rst for quick developer reference

Change-Id: Ie714d1a5d4cdf16ca3ad216b7729b8529d8038b9
---
 TESTING.rst | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 tox.ini     |  2 +-
 2 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 TESTING.rst

diff --git a/TESTING.rst b/TESTING.rst
new file mode 100644
index 0000000000..ca823f6416
--- /dev/null
+++ b/TESTING.rst
@@ -0,0 +1,86 @@
+====================
+Testing with Octavia
+====================
+
+
+Unit Testing
+------------
+
+Octavia uses tox to manage the virtual environments for running test cases.
+
+Install python-tox:
+
+.. code-block:: bash
+
+    $ pip install tox
+
+To run the full suite of tests maintained within Octavia.
+
+.. code-block:: bash
+
+    $ tox
+
+.. NOTE::
+
+    The first time you run ``tox``, it will take additional time to build
+    virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild
+    your virtualenv in a similar manner.
+
+
+To run tests for one or more specific test environments(for example, the most
+common configuration of Python 2.7 and PEP-8), list the environments with the
+``-e`` option, separated by spaces:
+
+.. code-block:: bash
+
+    $ tox -e py27,pep8
+
+See ``tox -l`` for the full list of available test environments.
+
+Functional Testing
+------------------
+
+Octavia creates a simulated API and handler for its functional tests.
+The tests then run requests against the mocked up API.
+
+To run the entire suite of functional tests:
+
+.. code-block:: bash
+
+    $ tox -e functional
+
+To run a specific functional test:
+
+.. code-block:: bash
+
+    $ tox -e functional octavia.tests.functional.api.v1.test_load_balancer
+
+Tests can also be run using partial matching, to run all API tests for v1:
+
+.. code-block:: bash
+
+    $ tox -e functional api.v1
+
+Additional options can be used while running tests. Two useful options that can
+be used when running tests are ``-- --until-failure`` which will run the tests
+in a loop until the first failure is hit, and ``-- --failing`` which if used
+after an initial run will only run the tests that failed in the previous run.
+
+Scenario Testing
+----------------
+
+Octavia uses Tempest to cover the scenario tests for the project.
+These tests are run against actual cloud deployments.
+
+To run the entire suite of scenario tests:
+
+.. code-block:: bash
+
+    $ tox -e scenario
+
+.. NOTE::
+
+    The first time running the Tempest scenario tests export the
+    Tempest configuration directory
+    (i.e. TEMPEST_CONFIG_DIR=/opt/stack/tempest/etc)
+
diff --git a/tox.ini b/tox.ini
index 085cfd872d..bf6ba457fc 100644
--- a/tox.ini
+++ b/tox.ini
@@ -56,7 +56,7 @@ commands = oslo_debug_helper {posargs}
 commands = flake8
 	   # RST linter
            doc8 specs doc/source octavia \
-           CONSTITUTION.rst HACKING.rst README.rst
+           CONSTITUTION.rst HACKING.rst README.rst TESTING.rst
 	   # Run security linter
            bandit -r octavia -ll -ii -x octavia/tests
            # Make sure specs follow our template