add instructions for running the tests

Add instructions for setting up the database user needed for the tests
and for overriding the test timeout on "slow" systems.

Change-Id: I2d45b21e07ff0810f833cfef6cd3aa2ffa409f46
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

doc/source/contributing.rst

@@ -1 +1,38 @@
-.. include:: ../../CONTRIBUTING.rst
+.. include:: ../../CONTRIBUTING.rst
+
+Running the Tests
+-----------------
+
+The test suite includes functional tests that use a MySQL database, so
+you must configure a database user.
+
+For MySQL you can use the following commands::
+
+ mysql -u root
+ mysql> CREATE USER 'openstack_citest'@'localhost' IDENTIFIED BY
+        'openstack_citest';
+ mysql> GRANT ALL PRIVILEGES ON * . * TO 'openstack_citest'@'localhost';
+ mysql> FLUSH PRIVILEGES;
+
+Storyboard uses tox_ to manage its unit and functional tests. After
+installing tox and downloading the storyboard source, run the tests
+with::
+
+  $ tox -e py27
+
+or for Python 3::
+
+  $ tox -e py35
+
+And to run the style-checker and static analysis tool::
+
+  $ tox -e pep8
+
+On slower systems, the database migrations may take longer than the
+default timeout of 60 seconds. To override the timeout, set the
+``OS_TEST_TIMEOUT`` environment variable. For example, to set the
+timeout to 2 minutes, run::
+
+  $ OS_TEST_TIMEOUT=120 tox -e py27
+
+.. _tox: https://tox.readthedocs.io/en/latest/