Incorrect branch/path coverage totals for uncovered files

[theseer]

Q	A
php-code-coverage version	10.1.3
PHP version	8.2.9
Driver	Xdebug
Xdebug version (if used)	3.2.2
Installation Method	PHPUnit PHAR
Usage Method	PHPUnit
PHPUnit version (if used)	10.3.1

The above 100% - 5/5 total for serializer is wrong, as the next screenshot shows:

The 100% - 5/5 total is only correct for the tested/covered files of this folder. Given there are untested/uncovered files present, that total should be less than 100%, and whatever the amount of branches might be ;)

I do realize we probably do not have that information (hence the n/a). But then we probably shouldn't calculate the total?

[sebastianbergmann]

@dvdoug Do you have any insight on this? Thanks!

[dvdoug]

I do realize we probably do not have that information (hence the n/a)

Yes, it's exactly that - the branches/paths are calculated by Xdebug, so if a file isn't processed then it's unknown (N.B. processed does not mean tested, merely loaded is sufficient). For the purposes of the statistical calculations, unknown is treated as 0 (see https://github.com/sebastianbergmann/php-code-coverage/blob/main/src/Node/File.php#L393 etc)

For v9, anyone who had processUncoveredFiles set to true wouldn't encounter this, as all files would be include()d but that setting doesn't exist anymore.

But then we probably shouldn't calculate the total?

I wouldn't recommend that, because that would mean that the root-level stats would display n/a if there was even a single uncovered file in the entire report - but maybe the number could be displayed with an asterisk and a tooltip that explains it's based on partial data?

[sebastianbergmann]

@dvdoug Thank you for your insight!

[sebastianbergmann]

When branch/path coverage is collected using Xdebug, files that were never loaded during tests lack branch/path coverage data. This is because Xdebug can only calculate branches and paths for files it actually processes at runtime.

These uncovered files are included in the report through RawCodeCoverageData::fromUncoveredFile(), which uses static analysis to create synthetic line coverage data. However, this method passes an empty array ([]) for function coverage, meaning no branch/path information exists for these files.

The consequence is misleading totals. For example, a directory with 3 covered files (5/5 branches each) and 2 uncovered files displays "100% - 15/15" for branch coverage. The uncovered files contribute 0 executable branches and 0 executed branches, making them invisible in the aggregation. The total should reflect that branch data is incomplete.

At the individual file level, the report correctly shows "n/a" for branches/paths when numExecutableBranches === 0. But the directory rolls up these zeros, and the Percentage class returns 100% when the total is 0, so the incomplete data is silently absorbed into the parent totals.

I explored two approaches to address this issue.

Approach 1: Track branch coverage data availability

Track whether each file has branch/path coverage data as a first-class concept in the node model, and let renderers indicate when totals are based on incomplete data.

Advantages

• No code execution, no side effects
• Users see that the total is based on partial data

Disadvantages

• The branch/path coverage totals remain numerically incomplete. They report accurately what was measured, but cannot include data that does not exist.

Approach 2: Process uncovered files through the driver

When branch/path coverage is active, use include_once to load uncovered files while Xdebug is collecting coverage data, similar to the processUncoveredFiles feature that existed in version 9 and was removed in version 10.

Why I decided against this

• include_once actually executes the code in the file, which can cause side effects
• This is one of the reasons the processUncoveredFiles functionality was removed in version 10
• It conflates "loading code for analysis" with "executing code", which is fundamentally unsafe for a testing tool