Getting Started

Minimal Steps

Verify PHPSpec Usage: Ensure phpspec/phpspec is installed in your project (composer show phpspec/phpspec). The adapter auto-detects it via infection/extension-installer.
Install the Adapter:
```
composer require --dev infection/phpspec-adapter
```
No manual configuration is required—the adapter registers automatically via Infection’s auto-discovery.
Run Infection:
```
vendor/bin/infection --test-framework=phpspec
```
Omit --test-framework if PHPSpec is your only test framework; Infection auto-detects it.
Check Output: Review the mutation report (e.g., infection.log) for:
- Survived mutations: Tests that failed to catch injected bugs.
- Killed mutations: Tests that correctly identified changes (high confidence).

First Use Case: Validating PHPSpec Test Coverage

Scenario: Your team relies on PHPSpec for BDD-style testing but wants to ensure tests aren’t brittle or missing edge cases. Workflow:

Run Infection with PHPSpec:
```
vendor/bin/infection --test-framework=phpspec --threads=4 --min-msi=90
```
- --threads=4: Parallelize mutations (critical for large codebases).
- --min-msi=90: Require 90% Mutation Score Improvement (only report projects meeting this threshold).
Triage Results:
- Focus on survived mutations in critical paths (e.g., payment logic).
- Use PHPSpec’s --format=pretty to debug why a test missed a mutation.

Expected Outcome:

Identify uncovered logic in PHPSpec specs (e.g., missing it_should_throw_when for invalid inputs).
Quantify test suite reliability (e.g., "Our PHPSpec tests kill 85% of mutations in UserService.php").

Where to Look First

Adapter Auto-Detection:
- Check vendor/infection/extension-installer logs if Infection fails to detect PHPSpec.
- Verify phpspec/phpspec is in composer.json under require-dev.
PHPSpec Configuration:
- The adapter respects your existing phpspec.yml (no overrides needed).
- Ensure extensions: in phpspec.yml are compatible (e.g., avoid custom extensions that break Infection’s interceptor).

Infection Configuration:

Customize infection.json5.dist for PHPSpec-specific needs:

{
  "test_framework": "phpspec",
  "threads": 2,
  "min_msi": 80,
  "include_paths": ["src", "tests/spec"],
  "exclude_paths": ["tests/spec/Unit/*"] // Skip unit specs if using BDD-only
}

Implementation Patterns

Core Workflow: Integrating into CI/CD

Step-by-Step:

Add to CI Pipeline (GitHub Actions example):
```
- name: Run Infection with PHPSpec
  run: vendor/bin/infection --test-framework=phpspec --threads=2 --min-msi=85
```
- Trigger: Run on push to main or pull_request events.
- Cache: Use actions/cache for vendor/ to speed up parallel runs.
Parallelization Strategy:
- Split mutations by file/directory to avoid memory issues:
```
vendor/bin/infection --test-framework=phpspec --threads=4 --include-paths="src/Service,src/Repository"
```
- Monitor memory usage (--memory-limit=1G) to adjust --threads.

Reporting:

Generate a HTML report for stakeholders:

vendor/bin/infection --test-framework=phpspec --report=html --output=infection-report

Upload as an artifact:

- uses: actions/upload-artifact@v3
  with:
    name: infection-report
    path: infection-report/

Integration Tips

1. Laravel-Specific Patterns

PHPSpec in Laravel: If using phpspec/phpspec with Laravel’s pestphp/pest (which supports PHPSpec-like syntax), configure Infection to target:
```
vendor/bin/infection --test-framework=phpspec --include-paths="tests/Feature,tests/Unit"
```

Service Provider Mutations: Focus mutations on app/Providers/ and app/Console/:

// infection.json5.dist
{
  "include_paths": ["app/Providers/*ServiceProvider.php"],
  "min_msi": 95 // Stricter for core logic
}

2. Custom PHPSpec Extensions

Problem: Some PHPSpec extensions (e.g., phpspec/extension-code-coverage) may conflict with Infection’s interceptor.
Solution:
- Exclude extension paths from mutations:
```
{
  "exclude_paths": ["vendor/phpspec/*"]
}
```
- Use --no-intercept for problematic extensions (limits mutation coverage).

3. Hybrid PHPSpec/PHPUnit Projects

Challenge: Infection may misdetect the test framework.

Fix: Explicitly specify the framework:

vendor/bin/infection --test-framework=phpspec --include-paths="tests/spec"
vendor/bin/infection --test-framework=phpunit --include-paths="tests/Unit"

4. Mutation Targeting

Prioritize Mutations: Use infection.json5.dist to focus on high-risk files:

{
  "include_paths": [
    "src/UseCases/**/*",
    "src/Repositories/**/*"
  ],
  "exclude_paths": [
    "src/Models/*", // Skip if already covered by Pest/PHPUnit
    "tests/spec/Integration/*" // Run separately
  ]
}

Advanced Patterns

1. Mutation Testing for PHPSpec "it" Blocks

Goal: Ensure individual PHPSpec examples are robust.
Approach:
- Use --mutate-only to target specific files:
```
vendor/bin/infection --test-framework=phpspec --mutate-only=src/UserService.php
```
- Review survived mutations in UserServiceSpec.php to add missing it_should cases.

2. CI Feedback Loops

Fail on Low MSI: Add a step to block PRs with MSI < threshold:

- name: Check Infection MSI
  run: |
    MSI=$(grep -oP 'Mutation Score Improvement: \K\d+' infection.log)
    if [ "$MSI" -lt 80 ]; then
      echo "MSI $MSI below threshold (80)."
      exit 1
    fi

3. Combining with PHPStan

Synergy: Use PHPStan’s rules to catch static issues, then Infection to validate dynamic behavior.
Workflow:
1. Run PHPStan:
```
vendor/bin/phpstan analyse --level=max
```
2. Run Infection:
```
vendor/bin/infection --test-framework=phpspec --min-msi=90
```
3. Triage: Fix PHPStan errors first, then address Infection’s survived mutations.

Gotchas and Tips

Pitfalls

1. False Positives in Mutation Detection

Symptom: Infection reports "no mutations" or crashes with NoCodeCoverageException.

Root Cause:

PHPSpec specs are not generating coverage data (e.g., missing phpunit.xml config).

Solution: Ensure phpspec.yml includes:

extensions:
  PhpSpec\Extension\CodeCoverageExtension:
    format: [clover]
    output: [coverage/clover.xml]

Then configure Infection to use the coverage file:

// infection.json5.dist
{
  "coverage": "coverage/clover.xml"
}

2. PHPSpec Extensions Breaking Interception

Symptom: Mutations are not applied or tests hang.
Common Culprits:
- Custom PHPSpec extensions that hook into runtime (e.g., logging, mocking).
- Solution:
  - Temporarily disable extensions during Infection runs:
```
vendor/bin/infection --test-framework=phpspec --no-intercept-extensions
```
  - Or exclude extension paths (see Integration Tips above).

3. Memory Leaks in Parallel Runs

Symptom: Infection crashes with Allowed memory exhausted on

Phpspec Adapter Laravel Package