phpunit.xml
Rama master · réplica de lectura del repositorio original.
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd" bootstrap="tests/bootstrap.php" colors="true" cacheDirectory=".phpunit.cache" executionOrder="random" failOnRisky="true" failOnWarning="true" beStrictAboutOutputDuringTests="true" displayDetailsOnTestsThatTriggerDeprecations="true" displayDetailsOnTestsThatTriggerWarnings="true" displayDetailsOnTestsThatTriggerErrors="true" displayDetailsOnSkippedTests="true">
<!--
============================================================================
S345 — displayDetailsOnSkippedTests="true" (on the root element above).
============================================================================
Before this, the only thing a run published about its skips was the COUNT in
"Tests: N, ..., Skipped: M." A count cannot distinguish the three things that
move it — a test STARTED skipping, a conditionally-skipped test became a
FAILURE, or a test DISAPPEARED — and it drifts on its own between runs because
this repo has legitimate environment-dependent skips (this repo's CI reports 3;
a developer box with no MySQL/Chromium/FFI reports ~259). Two audits were
forced to record skip movement as "unproven" for exactly that reason.
Why the CONFIG ATTRIBUTE and not the `display-skipped` CLI flag (CLI flags are
spelled here without their two leading hyphens, because an XML comment may not
contain them): the flag is per-invocation, and PHPUnit is invoked from five
places in this repo — twice in .github/workflows/phpunit.yml, twice in
.github/workflows/syncplay-e2e.yml, once in scripts/assertion-escape-audit.php —
plus every developer's shell. A flag would have to be re-added to each of them
and to every job added later — a hand-written list that never re-derives. This
attribute is read by every invocation that loads this file, so a new job cannot
silently ship without it.
Those sites are cited by FILE, not by line: the revision of this comment that
cited lines was made stale by its own commit. The count and the per-file
multiplicity are RE-DERIVED from the repo by
SkippedTestNameReportingTest::test_the_documented_invocation_sites_are_still_the_real_ones,
which fails if an invocation is added, moved or removed.
⚠ It is NOT universal, and the two exceptions are real rather than theoretical:
* `testdox`. PHPUnit builds the default result printer for a testdox run with
its displayDetailsOnSkippedTests constructor argument hardcoded false
(vendor/phpunit/phpunit/src/TextUI/Output/Facade.php:204-221; the
configuration value is not consulted on that path), so such a run counts its
skips in "Skipped: N" and can never name them, whatever this attribute or a
`display-skipped` flag say. syncplay-e2e.yml used to pass it and no longer
does, and SkippedTestNameReportingTest re-derives that ban from every .yml and
.yaml workflow, folding shell continuations first. scripts/skipped-test-names.sh detects testdox output and exits 5 saying
so, instead of blaming this file.
* the assertion-escape prober (scripts/assertion-escape-audit.php) captures
PHPUnit's output into a PHP variable and never echoes it, so no name set is
obtainable from that job. Its config is fine; its output never leaves the
process.
It is purely additive: this setting gates only two printList calls in
ResultPrinter::print() (lines 125-128), which APPEND lists. It does not change
the process exit status (that is `failOnSkipped`, a separate setting this repo
does not set) and it suppresses nothing.
It enables TWO lists, not one: printSkippedTestSuites() as well as
printSkippedTests(), because "Skipped: N" is the SUM of both event kinds
(SummaryPrinter.php:106). A skipped SUITE (class-level Requires attribute, or
markTestSkipped() in setUpBeforeClass()) is named under a different header and its
entries carry no "::"; scripts/skipped-test-names.sh parses both and emits a suite
as "SUITE:name".
scripts/skipped-test-names.sh turns the resulting output into a sorted,
`comm`-ready name set, and exits 4 rather than printing an empty set if this
attribute ever goes missing. tests/Unit/Support/SkippedTestNameReportingTest.php
fails if it is removed from this file.
-->
<testsuites>
<testsuite name="Unit">
<directory suffix="Test.php">tests/Unit</directory>
</testsuite>
<testsuite name="Integration">
<directory suffix="Test.php">tests/Integration</directory>
</testsuite>
<testsuite name="E2E">
<directory suffix="Test.php">tests/E2E</directory>
</testsuite>
</testsuites>
<groups>
<exclude>
<group>network</group>
</exclude>
</groups>
<!--
============================================================================
S141 — HOW TO READ THIS REPO'S COVERAGE NUMBERS. This is the ONE
authoritative statement; nothing else in the repo gets to contradict it.
============================================================================
THE POLICY (decided 2026-08-03, on the measurement below):
**This repo carries NO PHPUnit coverage metadata in tests/.** No `@covers`,
no `@coversNothing`, no `#[CoversClass]` / `#[CoversMethod]` /
`#[CoversFunction]` / `#[CoversNothing]`. Coverage is read WHOLE-RUN: a
file's figure is everything the suite executed in it.
THEREFORE:
* A 0.00% file is a file the suite NEVER EXECUTES. That reading is now
sound, and it was not before.
* A non-zero figure is what the suite executed. It is NOT a claim that
every executed line is asserted — see "the cost", below.
* The headline statement percentage, and the MIN_COVERAGE floor in
scripts/coverage-threshold-check.php, are a ratchet over that figure.
tests/Unit/Support/CoverageMetadataPolicyTest.php enforces all of it and
fails if metadata reappears, if this comment is deleted, or if
phpunit.xml starts requiring coverage metadata. Do NOT re-add an annotation
to silence it.
WHY — measured, not assumed. PHP 8.3.6 + PCOV 1.0.11, the CI invocation
(`php -d max_execution_time=0 vendor/bin/phpunit` with the clover report),
real MySQL 8.0, one identical random seed, the SAME tree twice with only the
603 annotation lines removed on the second pass. Both runs: Tests 8971,
Skipped 7, same failures.
metric (Clover /coverage/project/metrics) with @covers without
statements 65.49% 67.22%
41939/64039 43045/64039
methods 3110/6057 3231/6057
classes 160/672 175/672
files reporting 0.00% .................... 143 101
of which FALSE zeros (executed anyway) .. 42 0
of which reach 100% once un-narrowed .... 6 -
files that LOST coverage ................. - 0
So 42 of the 143 zeros — 29% of them — were files the suite runs and the
report called untested; six of those are executed in FULL. That is the
defect: "untested" and "attributed elsewhere by an annotation" were
indistinguishable, silently, and the natural reaction to a 0% file is to
write duplicate tests for behaviour that is already covered. (S96 and S121
each came within one step of doing exactly that.)
The mechanism, for the record: PHPUnit 10.5
`Framework/TestRunner.php:163` asks `Metadata/Api/CodeCoverage.php` for the
lines to be covered, and php-code-coverage
`CodeCoverage::applyCoversAndUsesFilter()` then does one of three things —
`false` (@coversNothing) CLEARS the whole run's data for that test, a
NON-EMPTY list keeps only the named units' listed lines and DELETES every
other file, and `[]` (no metadata) keeps everything. No warning is emitted
in any of the three cases.
Two further reasons the annotations had to go rather than be completed:
* The report was not one measurement but two incompatible ones mixed —
369 of 707 test files narrowed, 338 did not. An aggregate over that
mixture is not a measurement of anything.
* The annotations were inert as documentation and destructive as
configuration: this file sets neither `requireCoverageMetadata` nor
`beStrictAboutCoverageMetadata`, which are the only two settings that
make coverage metadata load-bearing. Nothing checked that a `@covers`
was correct, complete, or even resolvable.
THE COST, stated rather than hidden: whole-run coverage counts a line that
was merely EXECUTED, not necessarily asserted. 67.22% is therefore an upper
bound on "behaviour pinned by an assertion" in exactly the way 65.49% was a
lower bound on "code the suite runs". The defences against vacuous
execution are separate and already in place — the S120 assertion-escape
extension registered below, scripts/assertion-escape-audit.php in probe mode, and
per-step mutation testing. Coverage is not, and was never, that defence.
ONE DOCUMENTED EXCEPTION.
tests/Unit/Server/Http/Controllers/Admin/AdminSettingsControllerTest.php
still carries a `@covers`. A concurrent writer owned that file (uncommitted)
when this policy landed, so it was deliberately left alone rather than have
two writers edit one file. It is named explicitly in
CoverageMetadataPolicyTest's allow-list, and that test FAILS once the
annotation is gone, so the exception cannot rot into a permanent hole.
-->
<coverage>
<report>
<html outputDirectory="coverage-report"/>
<clover outputFile="coverage.xml"/>
<text outputFile="php://stdout" showUncoveredFiles="true" showOnlySummary="true"/>
</report>
</coverage>
<extensions>
<!--
S120 — reports any test where a failed assertion did not decide the test's
outcome (an assertion swallowed between the assertion and PHPUnit — by
`catch (\Throwable)`, `catch (\Exception)` or `catch (\RuntimeException)`, or by
a `return` inside a `finally` with no catch at all). See
tests/Support/AssertionEscape/EscapeCollector.php for the mechanism, for the four
blind spots (Assert::fail(), mock parameter/invocation rules,
markTestSkipped/Incomplete, and the failed-outcome budget itself), and for the
known false-positive class (a test that deliberately catches its own assertion
failure) together with the reasoning for providing no opt-out.
scripts/assertion-escape-check.php turns a report into a non-zero exit for CI.
DO NOT DELETE THE LINE BELOW. Removing this registration is silent: the guard
loads nothing, writes no report, and the CI check script exits 0 on a run full of
swallowed assertions. tests/Unit/Support/AssertionEscapeGuardWiringTest.php fails
if it goes missing — or is commented out, which it checks against the parsed
document rather than the file's text.
-->
<bootstrap class="Phlix\Tests\Support\AssertionEscape\AssertionEscapeGuardExtension"/>
<!--
S439 (finish-S167) — zero-residue census: snapshots /tmp/phlix_* before execution
and fails the run (named STDERR report + thrown subscriber warning, exit 1 via
failOnPhpunitWarning's true default) if the suite leaves any behind. Complements
TempDirMintGuardTest, which guards only the src-side logger mint sites and is
blind to test fixtures by construction. DO NOT DELETE THE LINE BELOW — its removal
would be silent; tests/Unit/Media/ZeroResidueCensusTest.php pins this wiring.
-->
<bootstrap class="Phlix\Tests\Support\ResidueCensus\ZeroResidueCensusExtension"/>
</extensions>
<php>
<env name="APP_ENV" value="testing"/>
<env name="DB_HOST" value="127.0.0.1"/>
<env name="DB_PORT" value="3306"/>
<env name="DB_DATABASE" value="phlix_test"/>
<env name="DB_USER" value="root"/>
<env name="DB_PASSWORD" value="root"/>
</php>
<source>
<include>
<directory suffix=".php">src</directory>
</include>
<exclude>
<directory suffix=".php">src/vendor</directory>
</exclude>
</source>
</phpunit>