PHPUnit: Tests Skipped or Errored by @requires PHP Version in CI

PHPUnit's @requires (or the #[RequiresPhp]/#[RequiresPhpExtension] attributes) skip tests whose PHP version or extension prerequisites are not met. In CI this either silently skips coverage you expected to run, or - with failOnSkipped/failOnIncomplete - turns the skip into a build failure.

What this error means

CI shows tests skipped with "@requires PHP 8.3" (or a required extension missing), or the build fails because the suite is strict about skipped tests. The runner PHP/extensions do not satisfy the requirement.

OK, but some tests were skipped!
Tests: 30, Assertions: 120, Skipped: 4.

App\Tests\EnumTest::testBacked
  Test requires PHP >= 8.3 (PHP 8.1.7 in use).

Common causes

Runner PHP is below the @requires version

The test declares a minimum PHP via @requires/#[RequiresPhp], and the CI runner is on an older PHP, so the test is skipped (or fails under strict skip settings).

A required extension is not loaded

#[RequiresPhpExtension] skips a test when the named extension is absent on the runner, hiding coverage you expected.

How to fix it

Match the CI PHP/extensions to the requirement

Upgrade the runner PHP (and enable required extensions) so the tests actually run.

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.3'
    extensions: intl, gmp

Make skips visible or strict deliberately

Decide whether skipped tests should fail the build, and configure PHPUnit accordingly.

<phpunit failOnSkipped="true" displayDetailsOnSkippedTests="true"></phpunit>

Test a matrix when requirements vary

1. Run a PHP version matrix so version-gated tests run on the right PHP.
2. Confirm php -m includes extensions referenced by #[RequiresPhpExtension].
3. Treat unexpected skips as gaps in coverage, not as passes.

How to prevent it

• Align CI PHP and extensions with the highest @requires constraints you depend on.
• Use a PHP version matrix for version-gated behavior.
• Surface skipped tests (displayDetailsOnSkippedTests) so silent gaps are visible.

Related guides