What causes "File %s exists, PHPT test %s will not be executed" in sebastianbergmann/phpunit?

Delete the stale .coverage file named in the message.

sebastianbergmann/phpunit · error · CodeCoverageFileExistsException

File %s exists, PHPT test %s will not be executed

Error message

File %s exists, PHPT test %s will not be executed

What it means

The PHPT TestCase constructor calls ensureCoverageFileDoesNotExist(): for a test.phpt it derives <testdir>/<basename>.coverage (basename with 'phpt' replaced by 'coverage') and throws CodeCoverageFileExistsException('File %s exists, PHPT test %s will not be executed') when that file already exists. The .coverage file is written during execution and removed afterwards, so a leftover one means a previous run crashed mid-test; re-running would corrupt or be corrupted by the stale file.

Source

Thrown at src/Runner/Phpt/TestCase.php:1017

     * @param array<non-empty-string, string> $sections
     * @param non-empty-string                $key
     */
    private function sectionOffset(array $sections, string $key): int
    {
        assert(isset($sections[$key]));

        return (int) $sections[$key];
    }

    /**
     * @throws CodeCoverageFileExistsException
     */
    private function ensureCoverageFileDoesNotExist(): void
    {
        $files = $this->coverageFiles();

        if (file_exists($files['coverage'])) {
            throw new CodeCoverageFileExistsException(
                sprintf(
                    'File %s exists, PHPT test %s will not be executed',
                    $files['coverage'],
                    $this->filename,
                ),
            );
        }
    }
}

View on GitHub (pinned to f123cdb2a2)

Solutions

Delete the stale <test>.coverage file named in the message.
Sweep the test directory for leftover *.coverage artifacts: find tests/ -name '*.coverage' -delete.
Investigate why the earlier run crashed mid-test (fatal error, OOM, timeout) so the artifact does not reappear.

Example fix

# before
phpunit tests/example.phpt
# => File tests/example.coverage exists, PHPT test tests/example.phpt will not be executed

# after
rm tests/example.coverage
phpunit tests/example.phpt

Defensive patterns

Strategy: validation

Validate before calling

// before running a PHPT suite, clear stale coverage artifacts
foreach (glob('tests/*.coverage') as $stale) {
    unlink($stale); // left over from a crashed previous run
}

// or targeted, per test file
$phpt     = 'tests/example.phpt';
$coverage = substr($phpt, 0, -4) . 'coverage';
if (file_exists($coverage)) {
    unlink($coverage);
}

Prevention

Clean *.coverage artifacts in CI before each PHPT run: find . -name '*.coverage' -delete.
Investigate and fix whatever crashed the earlier run (OOM, timeout, fatal error) so artifacts stop accumulating.
Do not commit *.coverage files; add them to .gitignore.

When it happens

Trigger: A previous PHPT test run crashed (fatal error, kill -9, OOM) between writing <test>.coverage and cleanup, leaving <test>.coverage on disk; constructing the PHPT TestCase again in the same or a later session.

Common situations: Interrupting a coverage-enabled PHPT run (Ctrl+C); a segfault or timeout inside a PHPT test; parallel runners restarting after a crash without cleanup.

Related errors

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