feat(report): introduce ReportEvent and related classes for report generation events

feat(junit): announce the written XML instead of printing its path
feat(json): announce the file written in `--log-json` mode
feat(teamcity): turn an announced report into the `testoReport` service message
feat(terminal): state an announced report as a plain path

A reporter dispatches its file instead of printing it, so it never has to know which renderer owns stdout. The early event carries the destination while the run tree is still open, which is the only moment an IDE can attach the TeamCity message to a node; the late one means the file can be read, which is what a human-facing line waits for.

Assisted-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: roxblnfk

composer.json

@@ -31,7 +31,7 @@
         "php": ">=8.2",
         "ext-tokenizer": "*",
         "internal/destroy": "^1.0",
-        "internal/path": "^1.2",
+        "internal/path": "^1.3",
         "psr/container": "1 - 2",
         "psr/event-dispatcher": "^1.0",
         "psr/log": "^2.0 || ^3.0",

core/Core/Report/ReportInfo.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Core\Report;
+
+/**
+ * What a reporter knows about the report it writes: how to identify it, what to call it, and where it
+ * lands.
+ *
+ * A reporter holds this from the moment its destination is settled — before the run, in the general case —
+ * and the announcement events carry it as their payload.
+ *
+ * @psalm-immutable
+ * @api
+ */
+final readonly class ReportInfo
+{
+    /**
+     * @param non-empty-string $format Machine-readable format id, e.g. `html` or `junit`. Names the dialect
+     *        a consumer would parse, not the file extension.
+     * @param non-empty-string $name Human-readable label for the report.
+     * @param \Stringable $path Where the report can be reached: an {@see \Internal\Path} for a file — the
+     *        entry file, `index.html` for a multi-file layout, never the directory — or a URL for a report
+     *        published to a service. Whatever form the reporter holds it in; a consumer that needs another
+     *        derives it from the string.
+     */
+    public function __construct(
+        public string $format,
+        public string $name,
+        public \Stringable $path,
+    ) {}
+}

core/Event/Report/ReportEvent.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Event\Report;
+
+use Testo\Core\Report\ReportInfo;
+
+/**
+ * A report a run produces, announced to whoever renders the run's output.
+ *
+ * A reporter dispatches these instead of printing anything itself, so it never has to know which
+ * renderer owns stdout. One event per report: a reporter that writes several formats, or one report per
+ * suite, announces each of them.
+ *
+ * The payload is the reporter's card; the subclass fixes the kind of report and the moment —
+ * {@see ReportFileGenerating} before a file is written, {@see ReportFileGenerated} after it. Subscribe
+ * here to hear every announcement whatever its kind and moment, since the dispatcher matches an event's
+ * parents, and to a concrete event when the moment is what you act on.
+ *
+ * @psalm-immutable
+ * @api
+ */
+abstract readonly class ReportEvent
+{
+    public function __construct(
+        public ReportInfo $info,
+    ) {}
+}

core/Event/Report/ReportFileGenerated.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Event\Report;
+
+/**
+ * Event triggered after a reporter has written a report file and closed it.
+ *
+ * The file exists and is complete, which makes this the event to act on for anything that reads the
+ * report — a checksum, an upload, a follow-up artifact. A renderer states it as a plain line; the TeamCity
+ * service message goes out earlier, on {@see ReportFileGenerating}.
+ *
+ * @psalm-immutable
+ * @api
+ */
+final readonly class ReportFileGenerated extends ReportEvent {}

core/Event/Report/ReportFileGenerating.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Event\Report;
+
+/**
+ * Event triggered when a reporter commits to writing a report file — as early as its destination is
+ * known, which for a reporter built from a whole run is the moment the session starts.
+ *
+ * The path is where the file **will** be: opening it on this event finds nothing, or a stale report from
+ * an earlier run, and a run that dies before writing leaves the promise unfulfilled. The event exists to
+ * state the artifact while the run's output is still open — the TeamCity renderer turns this one, and only
+ * this one, into the `##teamcity[testoReport …]` service message an IDE parses, and a message arriving
+ * after the last `testSuiteFinished` has no node in the run tree to attach to.
+ *
+ * {@see ReportFileGenerated} states the same file once it is written — the event to act on for anything
+ * that reads the report rather than points at it.
+ *
+ * @psalm-immutable
+ * @api
+ */
+final readonly class ReportFileGenerating extends ReportEvent {}

core/Output/JUnit/JUnitPlugin.php

@@ -6,13 +6,17 @@
 
 use Internal\Container\Container;
 use Internal\Path;
+use Psr\EventDispatcher\EventDispatcherInterface;
 use Testo\Common\EventListenerCollector;
 use Testo\Common\PluginConfigurator;
 use Testo\Core\Context\CaseInfo;
 use Testo\Core\Context\TestInfo;
 use Testo\Core\Value\TestType;
 use Testo\Event\Framework\SessionFinished;
 use Testo\Event\Framework\SessionStarting;
+use Testo\Core\Report\ReportInfo;
+use Testo\Event\Report\ReportFileGenerated;
+use Testo\Event\Report\ReportFileGenerating;
 use Testo\Event\Test\TestBatchFinished;
 use Testo\Event\Test\TestBatchStarting;
 use Testo\Event\Test\TestDataSetFinished;
@@ -184,6 +188,18 @@ public function configure(Container $container): void
 
         // Test Pipeline events (final event in the test lifecycle)
         $listeners->addListener(TestPipelineFinished::class, $this->onTestPipelineFinished(...));
+
+        // Registered after the listener that writes the file, so the late announcement follows the write.
+        $info = new ReportInfo('junit', 'JUnit report', $this->resolvedPath);
+        $dispatcher = $container->get(EventDispatcherInterface::class);
+        $listeners->addListener(
+            SessionStarting::class,
+            static fn(): mixed => $dispatcher->dispatch(new ReportFileGenerating($info)),
+        );
+        $listeners->addListener(
+            SessionFinished::class,
+            static fn(): mixed => $dispatcher->dispatch(new ReportFileGenerated($info)),
+        );
     }
 
     private static function formatDatasetSuffix(string|int $datasetKey, ?int $providerIndex): string

core/Output/Json/JsonPlugin.php

@@ -6,9 +6,14 @@
 
 use Internal\Container\Container;
 use Internal\Path;
+use Psr\EventDispatcher\EventDispatcherInterface;
 use Testo\Common\EventListenerCollector;
 use Testo\Common\PluginConfigurator;
+use Testo\Core\Report\ReportInfo;
 use Testo\Event\Framework\SessionFinished;
+use Testo\Event\Framework\SessionStarting;
+use Testo\Event\Report\ReportFileGenerated;
+use Testo\Event\Report\ReportFileGenerating;
 use Testo\Output\Json\Internal\JsonReport;
 
 /**
@@ -64,8 +69,24 @@ public function __construct(?string $outputPath = null, $stream = null)
     #[\Override]
     public function configure(Container $container): void
     {
-        $container->get(EventListenerCollector::class)
-            ->addListener(SessionFinished::class, $this->onSessionFinished(...));
+        $listeners = $container->get(EventListenerCollector::class);
+        $listeners->addListener(SessionFinished::class, $this->onSessionFinished(...));
+
+        $path = $this->path;
+        if ($path === null) {
+            return;
+        }
+
+        $info = new ReportInfo('json', 'JSON report', $path);
+        $dispatcher = $container->get(EventDispatcherInterface::class);
+        $listeners->addListener(
+            SessionStarting::class,
+            static fn(): mixed => $dispatcher->dispatch(new ReportFileGenerating($info)),
+        );
+        $listeners->addListener(
+            SessionFinished::class,
+            static fn(): mixed => $dispatcher->dispatch(new ReportFileGenerated($info)),
+        );
     }
 
     private function onSessionFinished(SessionFinished $event): void

core/Output/Teamcity/Teamcity/Formatter.php

@@ -374,6 +374,32 @@ public static function compilationFinished(string $compiler): string
         return self::formatMessage('compilationFinished', ['compiler' => $compiler]);
     }
 
+    /**
+     * Formats the announcement of a generated report.
+     *
+     * Non-standard: the TeamCity server ignores it, and an IDE plugin parses it explicitly to offer opening
+     * the report. `path` is absolute inside the execution environment, which a container or a remote
+     * interpreter makes meaningless on the consumer's machine — hence `relativePath` beside it, omitted
+     * when the report lies outside the working directory.
+     *
+     * @param non-empty-string $format Format id, e.g. `html`.
+     * @param non-empty-string $path Absolute path of the entry file in the execution environment.
+     * @param non-empty-string|null $relativePath The same file relative to the working directory.
+     * @param non-empty-string $name Human-readable label.
+     * @return non-empty-string
+     */
+    public static function testoReport(
+        string $format,
+        string $path,
+        ?string $relativePath,
+        string $name,
+    ): string {
+        $attributes = ['format' => $format, 'path' => $path, 'name' => $name];
+        $relativePath === null or $attributes['relativePath'] = $relativePath;
+
+        return self::formatMessage('testoReport', $attributes);
+    }
+
     /**
      * Formats a TeamCity service message.
      *

core/Output/Teamcity/Teamcity/TeamcityLogger.php

@@ -4,6 +4,7 @@
 
 namespace Testo\Output\Teamcity\Teamcity;
 
+use Internal\Path;
 use Testo\Assert\State\Assertion\ComparisonFailure;
 use Testo\Common\Environment;
 use Testo\Common\Info;
@@ -17,6 +18,7 @@
 use Testo\Core\Context\TestResult;
 use Testo\Core\Log\Message;
 use Testo\Core\Value\Status;
+use Testo\Core\Report\ReportInfo;
 use Testo\Output\Rendering\StackTrace;
 
 /**
@@ -339,6 +341,32 @@ public function logEmptyRun(): void
         $this->publish(Formatter::buildProblem('No tests were executed', 'testo.noTests'));
     }
 
+    public function logReport(ReportInfo $report): void
+    {
+        # A file report states a `Path` and gets both forms of it; any other location is announced as it
+        # stands, since resolving a URL against the working directory would name nothing.
+        $location = $report->path;
+
+        /**
+         * @var \Stringable $absolute Absolute path or URL
+         * @var Path|null $relative Relative path or null
+         */
+        [$absolute, $relative] = match (true) {
+            !$location instanceof Path => [$location, null],
+            $location->isAbsolute() => [$location, $location->tryRelative(Path::create(\getcwd() ?: ''))],
+            default => [$location->absolute(), $location],
+        };
+
+        $relative === null or $relative->isWithin() or $relative = null;
+
+        $this->publish(Formatter::testoReport(
+            format: $report->format,
+            path: (string) $absolute,
+            relativePath: $relative === null ? null : (string) $relative,
+            name: $report->name,
+        ));
+    }
+
     /**
      * Handles single test result based on status.
      *

core/Output/Teamcity/TeamcityPlugin.php

@@ -12,6 +12,7 @@
 use Testo\Event\Framework\SessionFinished;
 use Testo\Event\Framework\SessionStarting;
 use Testo\Event\Message\MessageReceived;
+use Testo\Event\Report\ReportFileGenerating;
 use Testo\Event\Test\TestBatchFinished;
 use Testo\Event\Test\TestBatchStarting;
 use Testo\Event\Test\TestDataSetFinished;
@@ -71,6 +72,9 @@ public function configure(Container $container): void
         $listeners->addListener(SessionStarting::class, $this->onSessionStarting(...));
         $listeners->addListener(SessionFinished::class, $this->onSessionFinished(...));
 
+        // Report files announced by any reporter plugin
+        $listeners->addListener(ReportFileGenerating::class, $this->onReportFileGenerating(...));
+
         // Messenger output — streamed in real time as stdout/stderr for the current test.
         $listeners->addListener(MessageReceived::class, $this->onMessageReceived(...));
 
@@ -115,6 +119,11 @@ private function onSessionFinished(SessionFinished $event): void
         $event->result->summary->total() === 0 and $this->logger->logEmptyRun();
     }
 
+    private function onReportFileGenerating(ReportFileGenerating $event): void
+    {
+        $this->logger->logReport($event->info);
+    }
+
     private function onMessageReceived(MessageReceived $event): void
     {
         $identity = $event->identity;