From a9ab62d54d0e7e35de6db88694d11c8afb6f23e5 Mon Sep 17 00:00:00 2001
From: Derick Rethans <github@derickrethans.nl>
Date: Wed, 6 Aug 2025 10:05:27 +0100
Subject: [PATCH] Add a brief section on options to the test runner, and -j

---
 docs/source/miscellaneous/running-tests.rst | 25 +++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/docs/source/miscellaneous/running-tests.rst b/docs/source/miscellaneous/running-tests.rst
index 0914f8404d1..bb2c56dcecd 100644
--- a/docs/source/miscellaneous/running-tests.rst
+++ b/docs/source/miscellaneous/running-tests.rst
@@ -58,6 +58,31 @@ Tester can easily execute tests selectively with as follows:
    ./sapi/cli/php run-tests.php ext/mbstring/*
    ./sapi/cli/php run-tests.php ext/mbstring/020.phpt
 
+*********************
+ Test Runner Options
+*********************
+
+The ``run-tests.php`` test runner has many options. You can see these options by using the ``-h``
+option with ``run-tests.php``.
+
+You can set options by specifying them on the command line when you run ``php run-tests.php`` or if
+you use ``make test`` through the ``TEST_PHP_ARGS`` environment variable:
+
+.. code:: shell
+
+   php run-tests.php -j24
+   # or
+   TEST_PHP_ARGS="-j24" make test
+
+Running Tests in Parallel
+=========================
+
+The test runner can run tests in parallel, by using the ``-j`` option:
+
+.. code:: shell
+
+   php run-tests.php -j24 ext/date/*.phpt
+
 **************
  Test results
 **************