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.