Skip to content

docs(phpunit): coverage driver choice + branch coverage tradeoff #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CybotTM merged 3 commits into from
Jul 15, 2026
Merged

docs(phpunit): coverage driver choice + branch coverage tradeoff #71

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dfb69d9
docs(phpunit): coverage driver choice + branch coverage tradeoff
CybotTM Jul 15, 2026
6222e35
Merge branch 'main' into docs/coverage-driver-tradeoff
CybotTM Jul 15, 2026
c65c86f
docs(phpunit): scope branchCoverage note to PHPUnit 13 (review)
CybotTM Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions skills/php-modernization/references/phpunit-modernization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,3 +162,28 @@ vendor/bin/phpunit 2>&1 | grep -E "Risky:|There (was|were) [0-9]+ risky"
vendor/bin/phpstan clear-result-cache
vendor/bin/phpstan analyse --no-progress
```

## Code coverage: driver choice + branch coverage

Two drivers, different capabilities — pick per need, don't default blindly:

| driver | line | branch | path | also does |
|--------|:----:|:------:|:----:|-----------|
| **pcov** | ✓ | ✗ | ✗ | nothing (coverage-only) |
| **xdebug** | ✓ | ✓ | ✓ | debug, profile, trace |

pcov is fast *because* it does less — line coverage only. Switching to pcov for speed permanently forecloses branch/path coverage. Keep xdebug when you want branch coverage; reach for pcov only for line-only CI where speed dominates.

**Enable branch coverage** (needs xdebug — pcov cannot):

```xml
<!-- valid in the bundled PHPUnit 13 schema (phpunit.xsd declares branchCoverage AND pathCoverage);
some AI review bots wrongly flag it as unsupported — verify against the vendored .xsd -->
<coverage branchCoverage="true"/>
```
```bash
# Cobertura carries branch data (branch-rate / branches-covered) for Codecov; Clover does not
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-cobertura cov.xml
```

**Cost:** xdebug branch coverage instruments every branch decision → **~6× slower** than a plain run; a full unit suite can blow past a 10-min job timeout. Run it off the gating path (nightly / `workflow_dispatch`), never on every PR, and raise that job's `timeout-minutes` accordingly.
Loading