docs(dev-env): a PHP coverage driver is a prerequisite, not an optional extra - #747
Merged
Merged
Conversation
…al extra phpunit.xml sets failOnRisky and beStrictAboutCoverageMetadata, and both are inert without a coverage driver. A test that executes a class its @Covers block does not name is risky, and risky is exit 1 in CI, where a driver is loaded. Without one locally the check cannot fire at all: composer check:strict passes and the suite prints 'OK, but there were issues!', which reads like a pass to anyone reading the summary line rather than the exit code. On 2026-09-10 that reddened every PHPUnit cell in dossiq and pipelinq within the same hour, on development, for the same reason. Neither author could have seen it before pushing. Adding a collaborator to an existing test is an ordinary edit that looks nothing like touching coverage metadata. Refs #746.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ruben chose "install pcov in the dev environment" for #746. This is the durable half of that: the prerequisite is now written down, with the reason.
Why it belongs under Prerequisites rather than under testing
phpunit.xmlsetsfailOnRiskyandbeStrictAboutCoverageMetadata. Both are inert without a coverage driver. A test that executes a class its@coversblock does not name is risky, and risky means exit 1 — in CI, where a driver is loaded. Locally, with no driver, the check cannot fire at all.composer check:strictpasses. The suite prints:and exits 1, which reads like a pass to anyone looking at the summary line rather than the exit code.
What it cost on 2026-09-10
Every PHPUnit cell in two repos, red on
development, within the same hour, for the same reason:EngineTaskInboxTestexecutesEngineInboxQuery(#2387)ConnectorEgressTestexecutesConnectorSourceRegister(test(egress): name ConnectorSourceRegister in the egress test's coverage metadata pipelinq#1910)Neither author could have seen it before pushing. Adding a collaborator to an existing test is an ordinary edit that looks nothing like touching coverage metadata. pipelinq's test file already carried a docblock note explaining the trap, written by whoever hit it last time on
FleetAppId— accurate, and it did not prevent the next occurrence, because the note lives in the file that already got fixed.What this does not do
It does not install anything. The machine change needs a password I do not have, so the command is written for whoever runs it. If someone later adds the driver to a provisioning script, this section is where it should point.