Add PHPUnit agent reporter to packaged config

Author: coisa

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Register ``ergebnis/phpunit-agent-reporter`` in the packaged ``phpunit.xml`` so AI agents receive compact PHPUnit JSON summaries without changing consumer overrides manually (#327)
 - Let `wiki`, `docs`, `tests`, `metrics`, and `reports` skip gracefully for guide-only repositories while keeping wiki/report workflows and published preview links aligned with the artifacts that were actually generated (#325)
 
 ## [1.25.0] - 2026-05-01

composer.json

@@ -44,6 +44,7 @@
         "container-interop/service-provider": "^0.4.1",
         "dg/bypass-finals": "^1.9",
         "ergebnis/agent-detector": "^1.1",
+        "ergebnis/phpunit-agent-reporter": "^0.3",
         "ergebnis/composer-normalize": "^2.51",
         "ergebnis/rector-rules": "^1.18",
         "fakerphp/faker": "^1.24",

docs/advanced/phpunit-extension.rst

@@ -3,7 +3,8 @@ PHPUnit Extension
 
 The packaged ``phpunit.xml`` is intentionally opinionated. Besides enabling
 strict PHPUnit flags, it registers
-``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``.
+``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension`` and
+``Ergebnis\PHPUnit\AgentReporter\Extension``.
 
 Runtime Chain
 -------------
@@ -16,6 +17,8 @@ Runtime Chain
    emitted during the run.
 4. ``FastForward\DevTools\PhpUnit\Event\TestSuite\JoliNotifExecutionFinishedSubscriber``
    builds a summary notification and sends it when the run finishes.
+5. ``Ergebnis\PHPUnit\AgentReporter\Extension`` replaces PHPUnit's normal
+   output with a compact JSON report when an agent runtime is detected.
 
 Why This Helps Consumer Projects
 --------------------------------
@@ -24,16 +27,18 @@ Why This Helps Consumer Projects
   needs it;
 - developers get a quick desktop summary without reading the full terminal
   scrollback;
+- agent-driven runs consume far less terminal context while still keeping
+  failure details and PHPUnit exit semantics intact;
 - event counts are available to the notification layer without adding ad-hoc
   test code.
 
 What to Remember When Overriding ``phpunit.xml``
 ------------------------------------------------
 
 If a consumer project replaces the packaged ``phpunit.xml``, it also replaces
-this extension unless it re-registers it manually. That is usually fine, but
-it explains why notifications or BypassFinals behavior may disappear after a
-local override.
+these extensions unless it re-registers them manually. That is usually fine,
+but it explains why notifications, BypassFinals behavior, or compact
+agent-oriented output may disappear after a local override.
 
 .. note::
 

docs/api/phpunit-support.rst

@@ -71,3 +71,8 @@ coverage metrics programmatically.
 
 These classes are especially relevant when a consumer project overrides the
 packaged ``phpunit.xml`` and wants to preserve the same runtime behavior.
+
+The packaged ``phpunit.xml`` also registers
+``Ergebnis\PHPUnit\AgentReporter\Extension`` so agent-driven PHPUnit runs can
+emit compact JSON summaries without changing the human-oriented default for
+normal terminal runs.

docs/configuration/tooling-defaults.rst

@@ -18,7 +18,7 @@ create them on day one.
      - Fallback Rector configuration.
    * - ``phpunit.xml``
      - ``tests``
-     - Registers ``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``.
+     - Registers ``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension`` and ``Ergebnis\PHPUnit\AgentReporter\Extension``.
    * - ``.php-cs-fixer.dist.php``
      - ``phpdoc``
      - Controls header and PHPDoc fixer behavior.

docs/faq.rst

@@ -70,8 +70,10 @@ Why did desktop notifications stop appearing after I customized PHPUnit?
 ------------------------------------------------------------------------
 
 If you replaced the packaged ``phpunit.xml``, you may also have removed
-``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``. Re-add the
-extension if you want the notification behavior back.
+``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension`` and
+``Ergebnis\PHPUnit\AgentReporter\Extension``. Re-add them if you want the
+notification behavior, BypassFinals support, and compact agent-oriented output
+back.
 
 Is ``AddMissingClassPhpDocRector`` enabled by default?
 ------------------------------------------------------

docs/usage/testing-and-coverage.rst

@@ -40,21 +40,24 @@ When ``--coverage=.dev-tools/coverage`` is used, PHPUnit writes:
 - ``.dev-tools/coverage/clover.xml``
 - ``.dev-tools/coverage/coverage.php``
 
-Built-In PHPUnit Extension
---------------------------
-
-The packaged ``phpunit.xml`` registers
-``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``.
-
-That extension wires together:
-
-- ``FastForward\DevTools\PhpUnit\Event\TestSuite\ByPassfinalsStartedSubscriber``,
-  which enables ``DG\BypassFinals`` when the suite starts;
-- ``FastForward\DevTools\PhpUnit\Event\EventTracer``, which records PHPUnit
-  events in memory;
-- ``FastForward\DevTools\PhpUnit\Event\TestSuite\JoliNotifExecutionFinishedSubscriber``,
-  which sends a desktop notification after the run when the local platform
-  supports it.
+Built-In PHPUnit Extensions
+---------------------------
+
+The packaged ``phpunit.xml`` registers:
+
+- ``FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension``, which
+  wires together:
+
+  - ``FastForward\DevTools\PhpUnit\Event\TestSuite\ByPassfinalsStartedSubscriber``,
+    which enables ``DG\BypassFinals`` when the suite starts;
+  - ``FastForward\DevTools\PhpUnit\Event\EventTracer``, which records PHPUnit
+    events in memory;
+  - ``FastForward\DevTools\PhpUnit\Event\TestSuite\JoliNotifExecutionFinishedSubscriber``,
+    which sends a desktop notification after the run when the local platform
+    supports it.
+- ``Ergebnis\PHPUnit\AgentReporter\Extension``, which replaces PHPUnit's
+  default verbose terminal output with a compact JSON summary when an agent
+  runtime is detected.
 
 Programmatic Coverage Access
 -----------------------------

phpunit.xml

@@ -10,6 +10,7 @@
          failOnRisky="true"
          failOnWarning="true">
     <extensions>
+        <bootstrap class="Ergebnis\PHPUnit\AgentReporter\Extension" />
         <bootstrap class="FastForward\DevTools\PhpUnit\Runner\Extension\DevToolsExtension" />
     </extensions>
 </phpunit>