From fb70c2e2571d7d795025274713c64a8280ef4504 Mon Sep 17 00:00:00 2001
From: Lingxian Kong <anlin.kong@gmail.com>
Date: Fri, 29 May 2020 22:35:13 +1200
Subject: [PATCH] Add doc for how to run functional test

Change-Id: Ia916d15fd587f9a2dee6e6a2cf9ee2c8ba386919
---
 doc/source/contributor/functional_test.rst | 28 ++++++++++++++++++++++
 doc/source/contributor/index.rst           |  1 +
 2 files changed, 29 insertions(+)
 create mode 100644 doc/source/contributor/functional_test.rst

diff --git a/doc/source/contributor/functional_test.rst b/doc/source/contributor/functional_test.rst
new file mode 100644
index 0000000000..10f3e3cc30
--- /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 9a0387bbdb..43b5a13bdc 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