Filter tests based on the PHP extensions they require

[sebastianbergmann]

Consider this test class:

<?php declare(strict_types=1);
namespace example;

use PHPUnit\Framework\Attributes\RequiresPhpExtension;
use PHPUnit\Framework\TestCase;

#[RequiresPhpExtension('mysqli')]
final class ExampleTest extends TestCase
{
    public function testSomething(): void
    {
        // ...
    }
}

When the test suite that contains the test case shown above is run then the output shown below is printed when the mysqli extension is not available in the PHP process that runs PHPUnit and the tests:

There was 1 skipped test:

1) example\ExampleTest::testSomething
PHP extension mysqli is required.

The test is skipped as its requirements are not met. This is better than triggering PHP errors related to unknown symbols such as classes or functions.

The RequiresPhpExtension attribute is commonly used in projects that have optional functionality that requires a PHP extension to work. When this extension is available then the tests are run, when the extension is not available then the tests are skipped.

It is sometimes desirable to have separate continuous integration jobs that use different PHP configurations where, for example, some extensions are available or not available. In certain scenarios it would be nice to filter tests based on the PHP extensions they require.

Proposal

Implement a CLI option named --requires-php-extension mysqli for PHPUnit's test runner that only runs tests that have a #[RequiresPhpExtension('mysqli')] attribute.

[sebastianbergmann]

@xabbuh You requested the following functionality at SymfonyLive Berlin:

1. Implement a CLI option to write the identifiers of tests that are skipped to a file
2. Implement a CLI option to select the tests to be run based on a list of test identifiers that is read from a file

The second part is already tracked in #3387, but before I think about the first part I would like to understand your use case, which we did not discuss in person unfortunately.

On the train home from Berlin, I remembered a discussion with somebody else from the Symfony community (sorry, forgot with whom) where our conversation started similar to the one we had. The result of that conversation was to implement the feature that was the topic of this issue. Does that make sense to you?

[xabbuh]

Thank you for reaching out. So here is what we do in the Symfony CI: For our tests on Windows we first run the whole test suite with as few PHP extensions as possible. The tests that have been executed successfully are recorded. After that we enable all PHP extensions and run the whole test die again. But this time we skip all tests that have already been run successfully with the minimal configuration before.

[sebastianbergmann]

I think that what you need / want to do should be possible with --requires-php-extension.

[xabbuh]

This looks like it really solves our specific use case without the need for #3387. 🥳 Thank you for the heads up. It really helps us moving forward.