Phpspec Adapter Laravel Package

Technical Evaluation

Architecture Fit

• Seamless PHPSpec Integration: Designed as a test framework adapter for Infection, this package adheres to Infection’s adapter contract, ensuring compatibility with its core mutation-testing engine. The architecture is modular, with clear separation between:
  • Configuration parsing (handles PHPSpec’s YAML/Neon formats).
  • Mutation execution (leverages Infection’s mutation engine).
  • Result validation (checks test outcomes post-mutation).
• Laravel/PHP Alignment: PHPSpec is commonly used in Laravel ecosystems (e.g., for domain-driven design or BDD workflows), making this adapter a natural fit for projects already invested in PHPSpec. The package’s auto-discovery mechanism reduces friction for Laravel apps using phpspec/phpspec.
• Performance Optimizations: Recent releases (e.g., v0.3.0+) include caching improvements (e.g., decoding PHPSpec YAML once, lazy-loading autoload templates) to mitigate Infection’s inherent runtime overhead (~30–60% slower than regular tests).

Integration Feasibility

• Zero-Configuration for Laravel: If phpspec/phpspec is already in composer.json, Infection’s extension-installer will auto-detect and install infection/phpspec-adapter. For manual setups:

  composer require --dev infection/phpspec-adapter
  

  • No PHPSpec config changes required: Uses existing phpspec.yml or phpspec.neon.
  • Laravel Service Provider: Can be bootstrapped via Laravel’s register() method if needed (though auto-discovery suffices).
• Dependency Synergy:
  • Infection: Must be v0.32.0+ (latest stable as of 2026-05-17).
  • PHPSpec: v6.0+ (compatible with Laravel’s modern PHP stacks).
  • PHP 8.3+: Hard requirement (dropped PHP 8.2 in v0.3.1).
• CI/CD Readiness: Outputs JUnit/XML reports compatible with tools like GitHub Actions, GitLab CI, or Jenkins. Can be gated as a pre-merge check or nightly job.

Technical Risk

• Parallelization: Infection supports --parallel flag.
• Caching: PHPSpec config and mutation templates are cached.
• Selective Mutation: Use --min-msi to skip trivial mutations (e.g., dead code). | | Laravel-Specific Quirks | PHPSpec’s autoloading may conflict with Laravel’s PSR-4. Adapter injects a custom autoloader template to handle this (fixed in v0.3.0 PR #97). Test in a staging environment before full adoption. | | Maintenance Burden | Low-risk:
• Open-source: Backed by Infection’s maintainers.
• Minimal Updates: Only requires composer update when Infection/PHPSpec major versions change.
• Laravel Ecosystem: Aligns with Laravel’s test-first culture (e.g., Pest’s rise suggests demand for robust testing tools). |

Key Questions for TPM

1. Test Coverage Baseline:
   • "What’s our current PHPSpec test coverage? Mutation testing is most valuable at >70% coverage—below that, results may be noisy."
2. CI/CD Pipeline Capacity:
   • "Can our CI handle 30–60% slower test runs? If not, we’ll need to parallelize or gate mutations to nightly builds."
3. Laravel-Specific Workflows:
   • "Do we use PHPSpec for unit tests, feature specs, or both? The adapter prioritizes unit-level mutations (feature specs may need custom configuration)."
4. Alerting Strategy:
   • "How should we surface mutation results? Slack alerts for killed mutations, or block PRs with <90% survival rate?"
5. Phasing Plan:
   • "Should we pilot this in a single Laravel module first, or roll out to the full codebase?"

Integration Approach

Stack Fit

• Laravel/PHP Ecosystem:
  • PHPSpec: Native integration (no config changes).
  • Infection: Compatible with Laravel’s Artisan commands (run via vendor/bin/infection).
  • Composer: Auto-installed via infection/extension-installer if PHPSpec is present.
  • PHPUnit/Pest: If mixed workflows exist, use Infection’s --test-framework flag to isolate PHPSpec mutations.
• Toolchain Synergy:
  • GitHub Actions/GitLab CI: Use Infection’s JUnit reporter for test dashboards.
  • Laravel Forge/Envoyer: Deploy only if mutation survival rate >85% (configurable threshold).
  • PHPStan/Pint: Adapter includes PHP-CS-Fixer path fixes (PR #116), reducing conflicts with Laravel’s coding standards.

Migration Path

Compatibility

• PHPSpec Features Supported:
  • YAML/Neon configs: Parsed and cached (PR #69).
  • Extensions: Handles null extensions gracefully (PR #65).
  • Coverage Tools: Uses default XML paths (PR #94).
• Laravel-Specific:
  • Service Providers: No changes needed (auto-discovery).
  • Artisan Commands: Run Infection via CLI or wrap in a custom command:

    // app/Console/Commands/MutationTest.php
    public function handle() {
        Artisan::call('infection', ['--test-framework' => 'phpspec']);
    }
    

• Anti-Patterns:
  • Avoid: Mixing PHPSpec and PHPUnit mutations in the same run (use separate configs).
  • Avoid: Running on legacy PHP 8.2 (adapter dropped support in v0.3