Implement TestCase::provideAdditionalInformation()

Author: sebastianbergmann

ChangeLog-12.2.md

@@ -7,6 +7,7 @@ All notable changes of the PHPUnit 12.2 release series are documented in this fi
 ### Added
 
 * `--with-telemetry` CLI option that can be used together with `--debug` to print debugging information that includes telemetry information
+* The `TestCase::provideAdditionalInformation()` method can now be used to emit a `Test\AdditionalInformationProvided` event
 * The new `Test\AfterLastTestMethodFailed`, `Test\AfterTestMethodFailed`, `Test\BeforeFirstTestMethodFailed`, `Test\BeforeTestMethodFailed`, `Test\PostConditionFailed`, `Test\PreConditionFailed` events are now emitted instead of `Test\AfterLastTestMethodErrored`, `Test\AfterTestMethodErrored`, `Test\BeforeFirstTestMethodErrored`, `Test\BeforeTestMethodErrored`, `Test\PostConditionErrored`, `Test\PreConditionErrored` when the `Throwable` extends `AssertionFailedError` to distinguish between errors and failures triggered in hook methods
 * The new `Test\PreparationErrored` event is now emitted instead of `Test\PreparationFailed` when the `Throwable` does not extend `AssertionFailedError` to distinguish between errors and failures triggered during test preparation
 * `Test\PreparationFailed::throwable()`

src/Event/Emitter/DispatchingEmitter.php

@@ -1024,6 +1024,23 @@ public function testPrintedUnexpectedOutput(string $output): void
         );
     }
 
+    /**
+     * @param non-empty-string $additionalInformation
+     *
+     * @throws InvalidArgumentException
+     * @throws UnknownEventTypeException
+     */
+    public function testProvidedAdditionalInformation(TestMethod $test, string $additionalInformation): void
+    {
+        $this->dispatcher->dispatch(
+            new Test\AdditionalInformationProvided(
+                $this->telemetryInfo(),
+                $test,
+                $additionalInformation,
+            ),
+        );
+    }
+
     /**
      * @param non-negative-int $numberOfAssertionsPerformed
      *

src/Event/Emitter/Emitter.php

@@ -240,6 +240,11 @@ public function testTriggeredPhpunitWarning(Code\Test $test, string $message): v
      */
     public function testPrintedUnexpectedOutput(string $output): void;
 
+    /**
+     * @param non-empty-string $additionalInformation
+     */
+    public function testProvidedAdditionalInformation(TestMethod $test, string $additionalInformation): void;
+
     /**
      * @param non-negative-int $numberOfAssertionsPerformed
      */

src/Event/Events/Test/AdditionalInformationProvided.php

@@ -0,0 +1,72 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Event\Test;
+
+use const PHP_EOL;
+use function sprintf;
+use PHPUnit\Event\Code\TestMethod;
+use PHPUnit\Event\Event;
+use PHPUnit\Event\Telemetry;
+
+/**
+ * @immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+final readonly class AdditionalInformationProvided implements Event
+{
+    private Telemetry\Info $telemetryInfo;
+    private TestMethod $test;
+
+    /**
+     * @var non-empty-string
+     */
+    private string $additionalInformation;
+
+    /**
+     * @param non-empty-string $additionalInformation
+     */
+    public function __construct(Telemetry\Info $telemetryInfo, TestMethod $test, string $additionalInformation)
+    {
+        $this->telemetryInfo         = $telemetryInfo;
+        $this->test                  = $test;
+        $this->additionalInformation = $additionalInformation;
+    }
+
+    public function telemetryInfo(): Telemetry\Info
+    {
+        return $this->telemetryInfo;
+    }
+
+    public function test(): TestMethod
+    {
+        return $this->test;
+    }
+
+    /**
+     * @return non-empty-string
+     */
+    public function additionalInformation(): string
+    {
+        return $this->additionalInformation;
+    }
+
+    /**
+     * @return non-empty-string
+     */
+    public function asString(): string
+    {
+        return sprintf(
+            'Test Provided Additional Information%s%s',
+            PHP_EOL,
+            $this->additionalInformation,
+        );
+    }
+}

src/Event/Events/Test/AdditionalInformationProvidedSubscriber.php

@@ -0,0 +1,20 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Event\Test;
+
+use PHPUnit\Event\Subscriber;
+
+/**
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+interface AdditionalInformationProvidedSubscriber extends Subscriber
+{
+    public function notify(AdditionalInformationProvided $event): void;
+}

src/Event/Facade.php

@@ -189,6 +189,7 @@ private function registerDefaultTypes(TypeMap $typeMap): void
             Test\BeforeTestMethodErrored::class,
             Test\BeforeTestMethodFailed::class,
             Test\BeforeTestMethodFinished::class,
+            Test\AdditionalInformationProvided::class,
             Test\ComparatorRegistered::class,
             Test\ConsideredRisky::class,
             Test\DeprecationTriggered::class,

src/Framework/TestCase.php

@@ -1242,6 +1242,17 @@ final protected function createPartialMock(string $type, array $methods): MockOb
         return $partialMock;
     }
 
+    /**
+     * @param non-empty-string $additionalInformation
+     */
+    final protected function provideAdditionalInformation(string $additionalInformation): void
+    {
+        Event\Facade::emitter()->testProvidedAdditionalInformation(
+            $this->valueObjectForEvents(),
+            $additionalInformation,
+        );
+    }
+
     protected function transformException(Throwable $t): Throwable
     {
         return $t;

tests/end-to-end/event/_files/AdditionalInformationTest.php

@@ -0,0 +1,22 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\TestFixture\Event;
+
+use PHPUnit\Framework\TestCase;
+
+final class AdditionalInformationTest extends TestCase
+{
+    public function testSuccess(): void
+    {
+        $this->assertTrue(true);
+
+        $this->provideAdditionalInformation('additional information');
+    }
+}

tests/end-to-end/event/additional-information.phpt

@@ -0,0 +1,31 @@
+--TEST--
+The right events are emitted in the right order for a successful test that provides additional information
+--FILE--
+<?php declare(strict_types=1);
+$_SERVER['argv'][] = '--do-not-cache-result';
+$_SERVER['argv'][] = '--no-configuration';
+$_SERVER['argv'][] = '--debug';
+$_SERVER['argv'][] = __DIR__ . '/_files/AdditionalInformationTest.php';
+
+require __DIR__ . '/../../bootstrap.php';
+
+(new PHPUnit\TextUI\Application)->run($_SERVER['argv']);
+--EXPECTF--
+PHPUnit Started (PHPUnit %s using %s)
+Test Runner Configured
+Event Facade Sealed
+Test Suite Loaded (1 test)
+Test Runner Started
+Test Suite Sorted
+Test Runner Execution Started (1 test)
+Test Suite Started (PHPUnit\TestFixture\Event\AdditionalInformationTest, 1 test)
+Test Preparation Started (PHPUnit\TestFixture\Event\AdditionalInformationTest::testSuccess)
+Test Prepared (PHPUnit\TestFixture\Event\AdditionalInformationTest::testSuccess)
+Test Provided Additional Information
+additional information
+Test Passed (PHPUnit\TestFixture\Event\AdditionalInformationTest::testSuccess)
+Test Finished (PHPUnit\TestFixture\Event\AdditionalInformationTest::testSuccess)
+Test Suite Finished (PHPUnit\TestFixture\Event\AdditionalInformationTest, 1 test)
+Test Runner Execution Finished
+Test Runner Finished
+PHPUnit Finished (Shell Exit Code: 0)

tests/unit/Event/Emitter/DispatchingEmitterTest.php

@@ -2531,6 +2531,47 @@ public function notify(Test\PrintedUnexpectedOutput $event): void
         $this->assertSame($output, $event->output());
     }
 
+    #[TestDox('testProvidedAdditionalInformation() emits Test\AdditionalInformationProvided event')]
+    public function testTestProvidedAdditionalInformationEmitsAdditionalInformationProvidedEvent(): void
+    {
+        $subscriber = new class extends RecordingSubscriber implements Test\AdditionalInformationProvidedSubscriber
+        {
+            public function notify(Test\AdditionalInformationProvided $event): void
+            {
+                $this->record($event);
+            }
+        };
+
+        $dispatcher = $this->dispatcherWithRegisteredSubscriber(
+            Test\AdditionalInformationProvidedSubscriber::class,
+            Test\AdditionalInformationProvided::class,
+            $subscriber,
+        );
+
+        $telemetrySystem = $this->telemetrySystem();
+        $test            = $this->testValueObject();
+
+        $emitter = new DispatchingEmitter(
+            $dispatcher,
+            $telemetrySystem,
+        );
+
+        $additionalInformation = 'addtional information';
+
+        $emitter->testProvidedAdditionalInformation(
+            $test,
+            $additionalInformation,
+        );
+
+        $this->assertSame(1, $subscriber->recordedEventCount());
+
+        $event = $subscriber->lastRecordedEvent();
+
+        $this->assertInstanceOf(Test\AdditionalInformationProvided::class, $event);
+        $this->assertSame($test, $event->test());
+        $this->assertSame($additionalInformation, $event->additionalInformation());
+    }
+
     #[TestDox('testFinished() emits Test\Finished event')]
     public function testTestFinishedEmitsTestFinishedEvent(): void
     {

tests/unit/Event/Events/Test/AdditionalInformationProvidedTest.php

@@ -0,0 +1,54 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Event\Test;
+
+use PHPUnit\Event\AbstractEventTestCase;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Small;
+
+#[CoversClass(AdditionalInformationProvided::class)]
+#[Small]
+final class AdditionalInformationProvidedTest extends AbstractEventTestCase
+{
+    public function testConstructorSetsValues(): void
+    {
+        $telemetryInfo         = $this->telemetryInfo();
+        $test                  = $this->testValueObject();
+        $additionalInformation = 'additional information';
+
+        $event = new AdditionalInformationProvided(
+            $telemetryInfo,
+            $test,
+            $additionalInformation,
+        );
+
+        $this->assertSame($telemetryInfo, $event->telemetryInfo());
+        $this->assertSame($test, $event->test());
+        $this->assertSame($additionalInformation, $event->additionalInformation());
+    }
+
+    public function testCanBeRepresentedAsString(): void
+    {
+        $event = new AdditionalInformationProvided(
+            $this->telemetryInfo(),
+            $this->testValueObject(),
+            'additional information',
+        );
+
+        $this->assertStringEqualsStringIgnoringLineEndings(
+            <<<'EOT'
+Test Provided Additional Information
+additional information
+EOT
+            ,
+            $event->asString(),
+        );
+    }
+}