first draft for documentation of extensions added with sebastianbergm…

…ann/phpunit#3002

src/configuration.rst

@@ -331,6 +331,28 @@ The XML configuration above corresponds to attaching the
         new stdClass
     );
 
+.. _appendixes.configuration.extensions:
+
+Registering TestRunner Extensions
+#################################
+
+The ``<extensions>`` element and its ``<extension>`` children
+can be used to register custom TestRunner extensions.
+
+:numref:`configuration.examples.RegisterExtension` shows how to register
+such an extension.
+
+.. code-block:: xml
+    :caption: Registering a TestRunner Extension
+    :name: configuration.examples.RegisterExtension
+
+      <?xml version="1.0" encoding="UTF-8"?>
+      <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/7.1/phpunit.xsd">
+          <extensions>
+              <extension class="Vendor\MyExtension"/>
+          </extensions>
+      </phpunit>
+
 .. _appendixes.configuration.php-ini-constants-variables:
 
 Setting PHP INI settings, Constants and Global Variables

src/extending-phpunit.rst

@@ -316,4 +316,60 @@ and the second value is the actual one.
     FAILURES!
     Tests: 2, Failures: 1.
 
+.. _extending-phpunit.TestRunner:
 
+Extending the TestRunner
+########################
+
+PHPUnit |version| supports TestRunner extensions that can hook
+into various events during the test execution.
+See :ref:`appendixes.configuration.extensions` for details on how
+to register extensions in PHPUnit's XML configuration.
+
+Each available event that the extension can hook into is represented by an
+interface that the extension needs to implement.
+:ref:`extending-phpunit.hooks` lists the available events in
+PHPUnit |version|.
+
+.. _extending-phpunit.hooks:
+
+Available Hook Interfaces
+-------------------------
+
+- ``AfterIncompleteTestHook``
+- ``AfterLastTestHook``
+- ``AfterRiskyTestHook``
+- ``AfterSkippedTestHook``
+- ``AfterSuccessfulTestHook``
+- ``AfterTestErrorHook``
+- ``AfterTestFailureHook``
+- ``AfterTestWarningHook``
+- ``BeforeFirstTestHook``
+- ``BeforeTestHook``
+
+:numref:`extending-phpunit.examples.TestRunnerExtension` shows an example
+for an extension implementing ``BeforeFirstTestHook`` and ``AfterLastTestHook``:
+
+.. code-block:: php
+    :caption: TestRunner Extension Example
+    :name: extending-phpunit.examples.TestRunnerExtension
+
+        <?php
+
+        namespace Vendor;
+
+        use PHPUnit\Runner\AfterLastTestHook;
+        use PHPUnit\Runner\BeforeFirstTestHook;
+
+        final class MyExtension implements BeforeFirstTestHook, AfterLastTestHook
+        {
+            public function executeAfterLastTest(): void
+            {
+                // called after the last test has been run
+            }
+
+            public function executeBeforeFirstTest(): void
+            {
+                // called before the first test is being run
+            }
+        }