Closes #3196

ChangeLog-7.3.md

@@ -16,6 +16,7 @@ All notable changes of the PHPUnit 7.3 release series are documented in this fil
   * The `--order-by=reverse` CLI option should now be used instead of `--reverse-order`
 * Implemented [#3161](https://github.com/sebastianbergmann/phpunit/pull/3161): Support for indexed arrays in `PHPUnit\Framework\Constraint\ArraySubset`
 * Implemented [#3194](https://github.com/sebastianbergmann/phpunit/issues/3194): `@covers class` (and `@uses class`) should include traits used by class
+* Implemented [#3196](https://github.com/sebastianbergmann/phpunit/issues/3196): Support for replacing placeholders in `@testdox` text with data provider values
 
 [7.3.0]: https://github.com/sebastianbergmann/phpunit/compare/7.2...7.3.0
 

phpstan-tests.neon

@@ -44,3 +44,4 @@ parameters:
         - tests/_files/phpunit-example-extension/tests/OneTest.php
         - tests/Regression/Trac/783/OneTest.php
         - tests/_files/3194.php
+        - tests/_files/RouterTest.php

src/Framework/TestCase.php

@@ -1121,6 +1121,14 @@ public function getDataSetAsString(bool $includeData = true): string
         return $buffer;
     }
 
+    /**
+     * Gets the data set of a TestCase.
+     */
+    public function getProvidedData(): array
+    {
+        return $this->data;
+    }
+
     /**
      * Override to run the test and assert its state.
      *
@@ -1546,14 +1554,6 @@ protected function prophesize($classOrInterface = null): ObjectProphecy
         return $this->getProphet()->prophesize($classOrInterface);
     }
 
-    /**
-     * Gets the data set of a TestCase.
-     */
-    protected function getProvidedData(): array
-    {
-        return $this->data;
-    }
-
     /**
      * Creates a default TestResult object.
      */

src/Util/TestDox/NamePrettifier.php

@@ -56,15 +56,35 @@ public function prettifyTestClass(string $className): string
 
     public function prettifyTestCase(TestCase $test): string
     {
-        $annotations = $test->getAnnotations();
+        $annotations                = $test->getAnnotations();
+        $annotationWithPlaceholders = false;
 
         if (isset($annotations['method']['testdox'][0])) {
             $result = $annotations['method']['testdox'][0];
+
+            if (\strpos($result, '$') !== false) {
+                $annotation = $annotations['method']['testdox'][0];
+                $result     = '';
+
+                $providedData = $this->mapTestMethodParameterNamesToProvidedDataValues($test);
+
+                foreach (\explode(' ', $annotation) as $word) {
+                    if (\strpos($word, '$') === 0) {
+                        $result .= $providedData[$word] . ' ';
+                    } else {
+                        $result .= $word . ' ';
+                    }
+                }
+
+                $result = \trim($result);
+
+                $annotationWithPlaceholders = true;
+            }
         } else {
             $result = $this->prettifyTestMethod($test->getName(false));
         }
 
-        if ($test->usesDataProvider()) {
+        if ($test->usesDataProvider() && !$annotationWithPlaceholders) {
             $result .= ' data set "' . $test->dataDescription() . '"';
         }
 
@@ -130,4 +150,18 @@ public function prettifyTestMethod(string $name): string
 
         return $buffer;
     }
+
+    private function mapTestMethodParameterNamesToProvidedDataValues(TestCase $test): array
+    {
+        $reflector          = new \ReflectionMethod(\get_class($test), $test->getName(false));
+        $providedData       = [];
+        $providedDataValues = $test->getProvidedData();
+        $i                  = 0;
+
+        foreach ($reflector->getParameters() as $parameter) {
+            $providedData['$' . $parameter->getName()] = $providedDataValues[$i++];
+        }
+
+        return $providedData;
+    }
 }

tests/TextUI/testdox-dataprovider-placeholder.phpt

@@ -0,0 +1,20 @@
+--TEST--
+phpunit --testdox RouterTest ../_files/RouterTest.php
+--FILE--
+<?php
+$_SERVER['argv'][1] = '--no-configuration';
+$_SERVER['argv'][2] = '--testdox';
+$_SERVER['argv'][3] = 'RouterTest';
+$_SERVER['argv'][4] = __DIR__ . '/../_files/RouterTest.php';
+
+require __DIR__ . '/../bootstrap.php';
+PHPUnit\TextUI\Command::main();
+--EXPECTF--
+PHPUnit %s by Sebastian Bergmann and contributors.
+
+Router
+ ✔ Routes /foo/bar to FooBarHandler
+
+Time: %s, Memory: %s
+
+OK (1 test, 1 assertion)

tests/_files/RouterTest.php

@@ -0,0 +1,34 @@
+<?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.
+ */
+
+use PHPUnit\Framework\TestCase;
+
+final class RouterTest extends TestCase
+{
+    /**
+     * @dataProvider routesProvider
+     * @testdox      Routes $url to $handler
+     */
+    public function testRoutesRequest(string $url, string $handler): void
+    {
+        $this->assertTrue(true);
+    }
+
+    public function routesProvider()
+    {
+        return [
+            '/foo/bar' => [
+                '/foo/bar',
+                FooBarHandler::class,
+                // ...
+            ]
+        ];
+    }
+}