# Add Mutation Testing to a PHP Library with Infection

Yes. An agent sets up Infection for your PHP library, runs it against the PHPUnit suite, adds fixtures for escaped mutants and a CI score floor, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-mutation-testing/php/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Add PHPStan Static Analysis to a PHP Library](https://getrush.ai/run/add-phpstan/php/)
- [Fix `Call to undefined function create_function()` after moving to PHP 8](https://getrush.ai/run/fix-create-function-removed/php/)
- [Fix "Deprecated: Creation of dynamic property is deprecated" in PHP 8.2](https://getrush.ai/run/fix-creation-of-dynamic-property-deprecated/php/)

## The same job on other stacks

- [Add Mutation Testing to a pytest Suite](https://getrush.ai/run/add-mutation-testing/pytest/)
- [Add Mutation Testing to a Tokio Project](https://getrush.ai/run/add-mutation-testing/tokio/)
- [Add Mutation Testing to a TypeScript Library](https://getrush.ai/run/add-mutation-testing/typescript-library/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
