Enhancement: Implement and emit TestDouble\TestStubCreated event

Fixes #51.

Co-authored-by: Andreas Möller <am@localheinz.com>
Co-authored-by: Arne Blankerts <Arne@Blankerts.de>

.psalm/baseline.xml

@@ -1,7 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <files psalm-version="4.1.1@16bfbd9224698bd738c665f33039fade2a1a3977">
   <file src="src/Event/DispatchingEmitter.php">
-    <MissingThrowsDocblock occurrences="42">
+    <MissingThrowsDocblock occurrences="43">
+      <code>dispatch</code>
       <code>dispatch</code>
       <code>dispatch</code>
       <code>dispatch</code>

src/Event/DispatchingEmitter.php

@@ -307,6 +307,17 @@ public function testDoubleTestProxyCreated(string $className, array $constructor
         ));
     }
 
+    /**
+     * @psalm-param class-string $className
+     */
+    public function testDoubleTestStubCreated(string $className): void
+    {
+        $this->dispatcher->dispatch(new TestDouble\TestStubCreated(
+            $this->telemetryInfo(),
+            $className
+        ));
+    }
+
     public function testSuiteAfterClassFinished(): void
     {
         $this->dispatcher->dispatch(new TestSuite\AfterClassFinished($this->telemetryInfo()));

src/Event/Emitter.php

@@ -124,6 +124,11 @@ public function testDoublePartialMockObjectCreated(string $className, string ...
      */
     public function testDoubleTestProxyCreated(string $className, array $constructorArguments): void;
 
+    /**
+     * @psalm-param class-string $className
+     */
+    public function testDoubleTestStubCreated(string $className): void;
+
     public function testSuiteAfterClassFinished(): void;
 
     public function testSuiteLoaded(TestSuite $testSuite): void;

src/Event/Registry.php

@@ -95,6 +95,7 @@ private static function registerDefaultTypes(TypeMap $typeMap): void
             TestDouble\MockObjectCreatedForTrait::class,
             TestDouble\PartialMockObjectCreated::class,
             TestDouble\TestProxyCreated::class,
+            TestDouble\TestStubCreated::class,
             TestSuite\AfterClassFinished::class,
             TestSuite\Loaded::class,
             TestSuite\RunFinished::class,

src/Event/TestDouble/TestStubCreated.php

@@ -0,0 +1,48 @@
+<?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\TestDouble;
+
+use PHPUnit\Event\Event;
+use PHPUnit\Event\Telemetry;
+
+final class TestStubCreated implements Event
+{
+    /**
+     * @var Telemetry\Info
+     */
+    private $telemetryInfo;
+
+    /**
+     * @var class-string
+     */
+    private $className;
+
+    /**
+     * @psalm-param class-string $className
+     */
+    public function __construct(Telemetry\Info $telemetryInfo, string $className)
+    {
+        $this->telemetryInfo = $telemetryInfo;
+        $this->className     = $className;
+    }
+
+    public function telemetryInfo(): Telemetry\Info
+    {
+        return $this->telemetryInfo;
+    }
+
+    /**
+     * @return class-string
+     */
+    public function className(): string
+    {
+        return $this->className;
+    }
+}

src/Event/TestDouble/TestStubCreatedSubscriber.php

@@ -0,0 +1,17 @@
+<?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\TestDouble;
+
+use PHPUnit\Event\Subscriber;
+
+interface TestStubCreatedSubscriber extends Subscriber
+{
+    public function notify(TestStubCreated $event): void;
+}

src/Framework/TestCase.php

@@ -1763,7 +1763,11 @@ protected function setLocale(...$args): void
      */
     protected function createStub(string $originalClassName): Stub
     {
-        return $this->createMockObject($originalClassName);
+        $stub = $this->createMockObject($originalClassName);
+
+        Event\Registry::emitter()->testDoubleTestStubCreated($originalClassName);
+
+        return $stub;
     }
 
     /**

tests/_files/NullEmitter.php

@@ -155,6 +155,10 @@ public function testDoubleTestProxyCreated(string $className, array $constructor
     {
     }
 
+    public function testDoubleTestStubCreated(string $className): void
+    {
+    }
+
     public function testSuiteAfterClassFinished(): void
     {
     }

tests/unit/Event/DispatchingEmitterTest.php

@@ -1288,6 +1288,41 @@ public function notify(TestDouble\TestProxyCreated $event): void
         self::assertSame($constructorArguments, $event->constructorArguments());
     }
 
+    public function testTestDoubleTestStubCreatedDispatchesTestDoubleTestStubCreatedEvent(): void
+    {
+        $className = self::class;
+
+        $subscriber = new class extends RecordingSubscriber implements TestDouble\TestStubCreatedSubscriber {
+            public function notify(TestDouble\TestStubCreated $event): void
+            {
+                $this->record($event);
+            }
+        };
+
+        $dispatcher = self::createDispatcherWithRegisteredSubscriber(
+            TestDouble\TestStubCreatedSubscriber::class,
+            TestDouble\TestStubCreated::class,
+            $subscriber
+        );
+
+        $telemetrySystem = self::createTelemetrySystem();
+
+        $emitter = new DispatchingEmitter(
+            $dispatcher,
+            $telemetrySystem
+        );
+
+        $emitter->testDoubleTestStubCreated($className);
+
+        self::assertSame(1, $subscriber->recordedEventCount());
+
+        $event = $subscriber->lastRecordedEvent();
+
+        self::assertInstanceOf(TestDouble\TestStubCreated::class, $event);
+
+        self::assertSame($className, $event->className());
+    }
+
     public function testTestSuiteAfterClassFinishedDispatchesTestSuiteAfterClassFinishedEvent(): void
     {
         $subscriber = new class extends RecordingSubscriber implements TestSuite\AfterClassFinishedSubscriber {

tests/unit/Event/TestDouble/TestStubCreatedTest.php

@@ -0,0 +1,32 @@
+<?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\TestDouble;
+
+use PHPUnit\Event\AbstractEventTestCase;
+
+/**
+ * @covers \PHPUnit\Event\TestDouble\TestStubCreated
+ */
+final class TestStubCreatedTest extends AbstractEventTestCase
+{
+    public function testConstructorSetsValues(): void
+    {
+        $telemetryInfo = self::createTelemetryInfo();
+        $className     = self::class;
+
+        $event = new TestStubCreated(
+            $telemetryInfo,
+            $className
+        );
+
+        self::assertSame($telemetryInfo, $event->telemetryInfo());
+        self::assertSame($className, $event->className());
+    }
+}