Pest Plugin Mutate Laravel Package

Getting Started

1. Install the plugin via Composer: composer require pestphp/pest-plugin-mutate --dev.
2. Ensure you have a passing Pest test suite — mutation testing only works on top of existing tests.
3. Run mutation testing on your codebase for the first time: vendor/bin/pest --mutate.
4. For local development, use mutate() inside a test file to limit scope — e.g., run only when testing a specific feature. Start with the default configuration (mutate()) and gradually add constraints like ->path('src').

Implementation Patterns

• Daily TDD/Refactor Workflow: Call mutate() directly in a test file (e.g., inside Feature/ServiceTest.php) to focus on one component at a time. This gives fast feedback and keeps CI load manageable.
• CI Guardrails: Configure a strict threshold (->min(90)) and only run on changed files (->changedOnly()) in PR checks to prevent regressions without slowing down builds.
• Staged Mutation Runs:
  • Local: Use ->retry() when iteratively fixing escaped mutants to prioritize known-good candidates.
  • CI: Use ->bail() to fail fast on low-hanging fruit (escaped or uncovered code).
• Config Reuse & Customization: Define named configs like 'default', 'arithmetic', or 'production-critical' in Pest.php, e.g.:

  use Pest\Mutate\Mutators;
  
  mutate('high-coverage')
      ->paths('src/Domain')
      ->mutators(Mutators::SET_HIGH_COVERAGE)
      ->min(100);
  

• Selective Mutation Sets: Use ->mutators(Mutators::SET_ARITHMETIC) to mutate only arithmetic operators for shallow, fast checks — ideal for quick checks in CI or early CI stages.

Gotchas and Tips

• Performance Bottlenecks: Without XDebug/PCOV, mutation testing defaults to no coverage detection, meaning all tests run for every mutation — this explodes runtime. Always enable a coverage driver locally and in CI if possible.
• changedOnly() Requires Git: This option only works in git repos and compares against main by default; pass a branch name to adjust (e.g., ->changedOnly('feature/xyz')). It relies on git diff and git merge-base.
• Cache Matters: Use --no-cache only when debugging; otherwise, cached results dramatically speed up runs — especially with ->retry().
• ->min() with failOnZeroMutations: false: Useful in new/empty directories where 0 mutations shouldn’t break the pipeline.
• mutate() vs CLI Flag: Using mutate() in tests implies --mutate; omit it if you only want CLI triggers. Avoid using both simultaneously unless intentional.
• Configuration Inheritance Not Yet Implemented: Though documented (->extends()), it’s currently unsupported — define configs explicitly.
• Stop Flags Are Aggressive: ->bail() stops on first escaped or uncovered mutant — great for CI safety, but can give incomplete reports during local exploration.
• Mutator Naming: CLI mutator names use underscores, e.g., ArithmeticPlusToMinus. In PHP, use constants like Mutators::ARITHMETIC_PLUS_TO_MINUS. Double-check spelling — typos silently ignore invalid mutators.