Support for replacing placeholders in @testdox text with data provider values

[sebastianbergmann]

By default, PHPUnit's TestDox result printer uses a test method's name:

<?php declare(strict_types=1);

use PHPUnit\Framework\TestCase;

final class RouterTest extends TestCase
{
    public function testRoutesRequest(): void
    {
        // ...
    }
}

Router
 ✔ Routes request

In the example above, the method name testRoutesRequest is displayed as Routes request. This is done by

• removing the test prefix,
• converting the remaining string to lowercase,
• converting the first character to uppercase,
• and inserting a space at camel-case word boundaries in the original string

This also works when snake-case (test_routes_request) is used instead.

Alternatively, PHPUnit's TestDox result printer case use a string provided using the @testdox annotation:

<?php declare(strict_types=1);

use PHPUnit\Framework\TestCase;

final class RouterTest extends TestCase
{
    /**
     * @testdox Routes request
     */
    public function testWithIndescriptiveName(): void
    {
        // ...
    }
}

Router
 ✔ Routes request

Things get "interesting" when we bring data providers into the mix:

<?php declare(strict_types=1);

use PHPUnit\Framework\TestCase;

final class RouterTest extends TestCase
{
    /**
     * @dataProvider routesProvider
     */
    public function testRoutesRequest(string $url, string $handler): void
    {
        // ...
    }

    public function routesProvider()
    {
        return [
            '/foo/bar' => [
                '/foo/bar',
                FooBarHandler::class,
                // ...
            ]
        ];
    }
}

Router
 ✔ Routes request data set "/foo/bar"

This is not nice to read.

This would be nice to read:

Router
 ✔ Routes /foo/bar to FooBarHandler

To make this possible, I propose the support for placeholders in @testdox strings that are replaced with values that come from a data provider:

    /**
     * @dataProvider routesProvider
     * @testdox      Routes $url to $handler
     */
    public function testRoutesRequest(string $url, string $handler): void
    {
        // ...
    }

[keradus]

👍 for it, but also, if there is no @testdox annotation, we can provide string that better distinguish test description from data provider description,
eg Routes request with data set "/foo/bar"
or Routes request | data set: "/foo/bar"

[sebastianbergmann]

@keradus Feel free to open a new ticket for that.

[adamcameron]

It would be good to document @ https://phpunit.readthedocs.io/en/9.5/annotations.html?highlight=testdox#testdox that one can also use $_dataName in the @testDox line, and it's the value of the key from the data provider's array, ie:

/**
@testDox $_dataName ($testCase)
@dataProvider provideCases
*/
function testSomething($testValue) {
    // etc
}

function provideCases() {
    return [
        'testing an OK value' => ['testValue' => 42],
        'testing a bad value' => ['testValue' => -1]
    ];
}

Yields this sort of thing in the test output:

* testing an OK value (42)
* testing a bad value (-1)

It would also be good to document the @testDox usage at https://phpunit.readthedocs.io/en/9.3/writing-tests-for-phpunit.html#data-providers, given it's reasonably closely related to some of the other documented functionality there.

(Mostly putting this here in case someone lands here from a search, wondering how to leverage that key name in the @testDox line.