Add doc for how to run functional test

Change-Id: Ia916d15fd587f9a2dee6e6a2cf9ee2c8ba386919

2 files changed, 29 insertions, 0 deletions

diff --git a/doc/source/contributor/functional_test.rst b/doc/source/contributor/functional_test.rst
new file mode 100644
index 00000000..10f3e3cc
--- /dev/null
+++ b/doc/source/contributor/functional_test.rst
@@ -0,0 +1,28 @@
+==========================
+How to run functional test
+==========================
+
+Install DevStack
+----------------
+Functional test defined for Trove is supposed to be running against DevStack. It's recommended that the host on which the DevStack is running should support nested virtualization, otherwise errors or timeout may occur during the testing. Refer to https://docs.openstack.org/devstack/latest/guides/devstack-with-nested-kvm.html for how to check and enable nested virtualization on the host.
+
+.. note::
+
+    The functional test is different with Trove tempest test.
+
+See `Install Trove in DevStack <https://docs.openstack.org/trove/latest/install/install-devstack.html>`_ for details.
+
+Run tests
+---------
+
+For example, to run functional test with mysql datastore version 5.7.29, in trove source code directory, run:
+
+.. code-block:: console
+
+    ADMIN_PASSWORD=password \
+    SERVICE_PASSWORD=password \
+    tox -e trovestack gate-tests mysql mysql 5.7.29
+
+* Parameters for ``gate-tests`` sub-command: ``<datastore_type> <test_group> <datastore_version>``. There are a few of test groups pre-defined: mysql, mysql-supported-single, mysql-supported-multi, mariadb-supported-single, mariadb-supported-multi, etc.
+* ``ADMIN_PASSWORD`` and ``SERVICE_PASSWORD`` are the passwords defined in the ``local.conf`` file in devstack directory.
+* By default, all the instances created during testing will be deleted automatically. For debugging purpose, if you want to keep the instances, you need to specify ``TESTS_DO_NOT_DELETE_INSTANCE=True``.
\ No newline at end of file
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 9a0387bb..43b5a13b 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -11,4 +11,5 @@ functionality, the following resources are provided.
 
    contributing
    design
+   functional_test
    testing