Document run_tests usage

docs/user_guide/ci.rst

@@ -13,3 +13,46 @@ The CI pipeline for this project is illustrated in the following diagram:
 .. image:: ../_static/ci_graph.svg
     :alt: CI Pipeline Diagram
     :align: center
+
+Running ``scripts/run_tests.py``
+--------------------------------
+
+Automated tests are executed through the ``scripts/run_tests.py`` helper.  The
+script requires several environment variables to be defined:
+
+``PPC_NUM_THREADS``
+    Number of threads to use.  The value is also exported as
+    ``OMP_NUM_THREADS``.
+
+``PPC_NUM_PROC``
+    Number of MPI processes to launch.
+
+``PPC_ASAN_RUN``
+    Set to ``1`` when sanitizers are enabled to skip ``valgrind`` runs (optional,
+    default ``0``).
+
+``PPC_IGNORE_TEST_TIME_LIMIT``
+    Set to ``1`` to disable test time limits (optional, default ``0``).
+
+The execution mode is selected with ``--running-type``.  The most common modes
+are ``threads`` for shared-memory backends and ``processes`` for MPI based
+tests.  ``performance`` mode runs performance benchmarks.
+
+Example usage:
+
+.. code-block:: bash
+
+   export PPC_NUM_THREADS=4
+   export PPC_NUM_PROC=2
+
+   # Multithreaded functional tests
+   python3 scripts/run_tests.py --running-type="threads"
+
+   # MPI functional tests
+   python3 scripts/run_tests.py --running-type="processes"
+
+   # Performance benchmarks
+   python3 scripts/run_tests.py --running-type="performance"
+
+Additional MPI arguments can be supplied with ``--additional-mpi-args`` when
+running in ``processes`` mode.