sebastianbergmann/phpunit · error · PHPUnit\TextUI\TestFileNotFoundException

Test file "%s" not found

Error message

Test file "%s" not found

What it means

TestSuiteBuilder::build() runs realpath() on every test file named on the command line; realpath() returns false when the path does not exist, and the Builder throws PHPUnit\TextUI\TestFileNotFoundException with the path exactly as given. This happens before any test is loaded, so nothing runs.

Source

Thrown at src/TextUI/Configuration/TestSuiteBuilder.php:77

    public function build(Configuration $configuration): TestSuite
    {
        $numberOfRuns = $configuration->repeat();
        $maxAttempts  = $configuration->retry();

        if ($numberOfRuns > 1) {
            // the --repeat CLI option takes precedence over the --retry CLI option
            $maxAttempts = 1;
        }

        if ($configuration->hasCliArguments() || $configuration->hasTestFilesFile()) {
            $arguments = [];

            if ($configuration->hasCliArguments()) {
                foreach ($configuration->cliArguments() as $cliArgument) {
                    $argument = realpath($cliArgument);

                    if ($argument === false) {
                        throw new TestFileNotFoundException($cliArgument);
                    }

                    $arguments[] = $argument;
                }
            }

            if ($configuration->hasTestFilesFile()) {
                if (!is_file($configuration->testFilesFile())) {
                    throw new RuntimeException('Cannot read from ' . $configuration->testFilesFile());
                }

                $directory = dirname($configuration->testFilesFile()) . DIRECTORY_SEPARATOR;

                $fileLines = file($configuration->testFilesFile());

                // @codeCoverageIgnoreStart
                if ($fileLines === false) {
                    throw new RuntimeException('Cannot read from ' . $configuration->testFilesFile());

View on GitHub (pinned to f123cdb2a2)

Solutions

  1. Verify the argument exists from your current directory: `ls tests/Unit/UserTest.php` with the exact string you pass
  2. Run from the project root or use an absolute path
  3. Update the stale file reference in your script/CI config after renames
  4. Check `git status` / `git log --follow` to find where the file went

Example fix

# before (file was renamed to AccountTest.php)
vendor/bin/phpunit tests/Unit/UserTest.php

# after
vendor/bin/phpunit tests/Unit/AccountTest.php
Defensive patterns

Strategy: validation

Validate before calling

$testFile = $argv[1] ?? '';

if ($testFile !== '' && !is_file($testFile)) {
    fwrite(STDERR, "Test file not found: {$testFile} (cwd: " . getcwd() . ')' . PHP_EOL);
    exit(2);
}

// safe to pass to phpunit now

Try / catch

try {
    $suite = (new \PHPUnit\TextUI\Configuration\TestSuiteBuilder)->build($configuration);
} catch (\PHPUnit\TextUI\TestFileNotFoundException $e) {
    // $e->getMessage() contains the exact unresolved argument;
    // verify cwd and file existence, fix the argument, and retry
}

Prevention

When it happens

Trigger: `vendor/bin/phpunit tests/Unit/UserTest.php` after the file was renamed to AccountTest.php; a typo in the path; a relative path used from a different working directory than assumed (e.g. running from tests/ instead of the project root).

Common situations: Test files renamed or moved during a refactor while scripts/CI configs still reference the old names; CI checking out a different branch with a different file layout; running phpunit from a subdirectory with root-relative paths.

Related errors

AI-assisted analysis of sebastianbergmann/phpunit@f123cdb2a2 (2026-08-23). Data as JSON: /api/errors/81eb3af65ffaa0c6. Report an issue: GitHub.