What the agent does
The agent reads how the library is tested before it installs anything, because Infection can only mutate what the suite already covers. In a library like erusev/parsedown, composer.json requires php >=7.2 and ext-mbstring, has one development dependency, phpunit/phpunit ^8.5.52|^9.6.33, and autoloads the Parsedown class with PSR-0 from the repository root, where the whole parser is one file, Parsedown.php. phpunit.xml.dist sets bootstrap="vendor/autoload.php" and one test suite named Parsedown that lists a single file, test/ParsedownTest.php; it has no coverage or source element. That test class is fixture-driven: its test_ method takes each .md file in test/data/ that has an .html beside it, turns safe mode on for names starting xss and strict mode on for names starting strict, and compares text() with the expected markup. .github/workflows/unit-tests.yaml runs one phpunit job on PHP 7.2 through 8.4 with shivammathur/setup-php@v2 and a plain composer install, and .gitignore lists composer.lock, so every matrix job resolves its own versions.
That last fact decides how Infection is installed. Packagist lists the current Infection line as requiring PHP ^8.3, so putting it in require-dev would either break composer install on the older matrix entries or make Composer pick a different, years-old Infection on each of them. The agent leaves composer.json alone and adds a separate mutation job on one recent PHP version that asks setup-php for tools: infection and coverage: pcov, installs the library's own dependencies, and runs the downloaded tool. It confirms that the Infection release it gets accepts the PHPUnit version Composer resolves on that PHP, and names the pair in the pull request rather than assuming it.
The configuration is an infection.json5 at the root. source.directories is . with vendor and test excluded, because the class under test sits beside composer.json rather than under src/; logs writes a text log and an HTML report and turns on GitHub annotations; mutators starts from @default. Infection runs the suite PHPUnit's own configuration names, which matters here: the second test file, test/CommonMarkTestWeak.php, downloads the CommonMark specification from raw.githubusercontent.com in its data provider and is run in CI with || true, so it must stay out of a run whose first requirement is a green suite. The agent also adds /infection.json5 export-ignore to .gitattributes, which already keeps /test and /phpunit.xml.dist out of release archives, and the log file names to .gitignore.
Then it runs the tool and reads the result instead of only wiring it. In its sandbox it installs a PHP that Infection supports with mbstring and pcov, runs composer install and vendor/bin/phpunit to see the baseline pass, and runs Infection with --threads=max --show-mutations. It groups the escaped mutants by method and, for each group, either adds a fixture pair under test/data/ (a .md and the .html Parsedown should produce) that kills them, or records why the mutant is equivalent. Once the score stops moving it sets minMsi and minCoveredMsi just under the measured values, so the job fails when a later change lowers the score and not on the day it is merged.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add mutation testing with Infection to this PHP library. Read composer.json, phpunit.xml.dist, .github/workflows/unit-tests.yaml, .gitattributes, .gitignore, the public methods of Parsedown.php and every PHP file under test/ first. Do not add Infection to require-dev: the library supports PHP versions Infection does not, and there is no lock file. Add an infection.json5 whose source is the repository root with vendor and test excluded, with a text log, an HTML report and GitHub annotations. Install a PHP version Infection supports with mbstring and pcov in your sandbox, run composer install and vendor/bin/phpunit, then run Infection with --threads=max --show-mutations and keep the output. Keep the CommonMark test file out of the mutation run. For escaped mutants, add fixture pairs under test/data that kill them or explain why each is equivalent, then set minMsi and minCoveredMsi just below the scores you measured. Add a mutation job to the workflow on one PHP version using setup-php with tools: infection and coverage: pcov, export-ignore the new config in .gitattributes, ignore the log files, and open a pull request that reports the scores before and after and the Infection and PHPUnit versions used.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that adds infection.json5, a mutation job in the existing workflow, one line in .gitattributes, the log names in .gitignore, and whatever fixture pairs under test/data/ the escaped mutants called for. Its description gives the mutation score and the covered-code score as measured before and after the new fixtures, the Infection and PHPUnit versions that produced them, the mutants left alive with the reason for each, and the two thresholds it set.
A reviewer reads the new fixtures the way they would read any Markdown test case: is this the HTML the parser should produce, or did the agent bless current behaviour to kill a mutant? They also decide whether the mutation job should block merging or only report. composer.json and the existing phpunit job are unchanged, so nothing about the supported PHP range moves.
Run it on every terminal hand-off
A maintainer who suspects the fixtures pass without pinning much behaviour sends this body from the terminal with the repository in resources and carries on with the release they were preparing. The run measures the suite against the real parser, so what comes back is a score with the surviving mutants listed, not a configuration file nobody has executed.
Send a request_id, a UUID, in the body so a retried start returns the run already under way. When the turn ends, GET /o/{org}/sessions/{id} names the pull request, and a follow-up message to the same session can ask it to raise the floor, to limit a pull request's run to the lines it changed, or to go after one method's survivors.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Mutation testing is compute spent to learn something, and the learning is in the list of survivors. Running it on a laptop ties up every core for the length of the run; here it runs in the agent's own sandbox, each Infection invocation and its full output stay in the run's record, and the pull request quotes the mutants that escaped and the fixtures that now catch them.
The same request fits a library whose code lives under src/, one that ships a lock file and can carry Infection in require-dev, or one tested with Pest. Each gets a configuration derived from its own Composer file and CI matrix, and a threshold measured on its own suite rather than a number copied from a guide.
Frequently asked questions
Why not add Infection with composer require --dev?
Because this library still tests on PHP 7.2 and commits no lock file. Packagist shows the current Infection releases need PHP 8.3 or newer, so a development requirement would fail to resolve on the old matrix entries or resolve to a much older Infection there. Installing it as a tool in one job keeps the other jobs exactly as they are.
Does Infection need Xdebug?
It needs a coverage driver so it only mutates lines a test executes. The job asks setup-php for PCOV, and Xdebug works as well. Without a driver Infection stops before mutating anything, which the agent would see in its own run before the workflow is pushed.
Will this slow down every pull request?
The mutation job is separate from the phpunit matrix, so the existing checks finish as before. Whether the new job is required is a branch setting the reviewer chooses. A follow-up can restrict pull request runs to changed lines and keep the full run for pushes to the default branch.
What happens to mutants no test can kill?
Some changes produce code that behaves identically, such as a reordered condition with no observable effect. The pull request lists each one it left alive with the reason, and the thresholds are set under the measured scores so those mutants do not fail the job.
More PHP jobs
The same job on other stacks
- Add Mutation Testing to a pytest Suite (pytest)
- Add Mutation Testing to a Tokio Project (Tokio)
- Add Mutation Testing to a TypeScript Library (TypeScript library)