Bridge Infection Laravel Package

Getting Started

Minimal Steps

1. Prerequisites:

   • Ensure Testo is installed and configured as your primary test framework:

     composer require --dev testo/testo
     

   • Install testo/codecov for coverage XML generation:

     composer require --dev testo/codecov
     

   • Configure Testo in testo.yaml (if not already done).

2. Install the Bridge:

   composer require --dev testo/bridge-infection
   

3. Configure Infection: Update infection.json to specify Testo as the test framework:

   {
     "testFramework": "testo",
     "include": ["tests/"],
     "threads": 4,
     "minimumDetection": 95,
     "timeLimit": 60
   }
   

4. First Run: Execute Infection to verify integration:

   vendor/bin/infection
   

   • Infection will auto-discover the bridge via infection/extension-installer.
   • Ensure Testo’s --teamcity and --filter flags are respected in mutant runs.

Where to Look First

• Testo Configuration: Verify testo.yaml includes coverage settings for testo/codecov.
• Infection Logs: Check for errors in Testo’s output parsing (e.g., JUnit/XML format).
• CI/CD Integration: Test locally before committing to CI pipelines (mutation testing is resource-intensive).

First Use Case

Identify Weak Tests in a Laravel Feature:

1. Run Infection on a specific test file:

   vendor/bin/infection --filter="Feature\AuthTest"
   

2. Review mutants killed by tests to spot gaps in test coverage.
3. Use --teamcity output in CI for detailed reporting:

   vendor/bin/infection --teamcity | tee results.xml
   

Implementation Patterns

Usage Patterns

1. Basic Mutation Testing Workflow

# Run Infection with Testo (auto-discovered)
vendor/bin/infection

# Target specific tests
vendor/bin/infection --filter="Feature\UserTest"

# Limit mutants to a single file
vendor/bin/infection --include="tests/Feature/UserControllerTest.php"

2. CI/CD Integration

• GitHub Actions Example:

  jobs:
    mutation-testing:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: shivammathur/setup-php@v2
          with:
            php-version: '8.2'
        - run: composer install
        - run: vendor/bin/infection --teamcity --threads=2
  

3. Parallel Execution

Leverage Infection’s threading to reduce runtime:

vendor/bin/infection --threads=4 --timeLimit=120

Workflows

Test-Driven Mutation Analysis

1. Run Infection:

   vendor/bin/infection --filter="Unit\Service\*" --min-detection=90
   

2. Analyze Results:
   • Focus on survived mutants (false negatives in your test suite).
   • Use Testo’s --filter to isolate problematic test files.

Coverage-Driven Mutation Testing

• Ensure testo/codecov generates XML coverage reports:

  # testo.yaml
  coverage:
    driver: xdebug
    output: build/coverage.xml
  

• Infection will use this to map mutants to specific tests.

Integration Tips

Laravel-Specific Considerations

• Database Transactions: Testo may not replicate Laravel’s transaction handling in mutants. Use --filter to exclude transaction-heavy tests if needed.
• Service Providers: Ensure Testo’s autoloader includes Laravel’s service providers (check testo.yaml for autoload paths).

Debugging Test Attribution

• If mutants aren’t attributed to tests:
  1. Verify testo/codecov generates PHPUnit-style XML.
  2. Check Infection’s logs for XML parsing errors.
  3. Ensure infection/include-interceptor is installed (required for Testo’s autoloading).

Customizing Testo’s CLI Flags

Infection passes Testo’s --filter and --teamcity flags automatically. To add custom flags:

// infection.json
{
  "testFramework": "testo",
  "testFrameworkOptions": ["--verbose", "--no-progress"]
}

Gotchas and Tips

Pitfalls

1. Missing Dependencies

• Error: Class 'Testo\Testo' not found.
  • Fix: Ensure testo/bridge-infection and testo/testo are installed. Run:

    composer require --dev testo/testo testo/bridge-infection
    

2. Coverage XML Mismatch

• Error: Infection fails to map mutants to tests.
  • Fix: Verify testo/codecov generates valid PHPUnit-style XML. Check:

    vendor/bin/testo --coverage --output=build/coverage.xml
    

  • Ensure the XML includes <testsuite> and <testcase> nodes.

3. Autoloading Issues

• Error: include_interceptor fails to load Testo classes.
  • Fix: Install infection/include-interceptor (v1+):

    composer require --dev infection/include-interceptor
    

  • Ensure Testo’s autoload paths are included in testo.yaml.

4. Laravel Environment Mismatch

• Error: Mutants fail due to missing Laravel services.
  • Fix: Mock Laravel dependencies explicitly in tests or use --filter to exclude problematic tests.

5. Performance Bottlenecks

• Error: Infection runs exceed time limits in CI.
  • Fix:
    • Increase timeLimit in infection.json.
    • Reduce --threads or exclude large test suites with --filter.
    • Run on a dedicated CI runner with more resources.

Debugging

Enable Verbose Logging

vendor/bin/infection --verbose

• Look for errors in Testo’s output parsing or autoloading.

Isolate Test Files

Use --filter to narrow down failing mutants:

vendor/bin/infection --filter="Unit\Service\UserServiceTest"

Check Infection’s Cache

Clear Infection’s cache if mutants behave inconsistently:

rm -rf .infection

Config Quirks

Testo’s --path Handling

• Infection converts --path values to be relative to projectDir. If paths are absolute, add this to infection.json:

  {
    "projectDir": "/absolute/path/to/project"
  }
  

JUnit Format Fallback

• If Testo’s JUnit output is malformed, Infection falls back to reflection. Ensure Testo’s --format=junit works:

  vendor/bin/testo --format=junit > build/test-results.xml
  

Extension Points

Custom Mutant Strategies

• Testo’s bridge doesn’t yet support custom Infection strategies (e.g., Infection\Strategies\TimeLimit). Track Testo’s roadmap for updates.

Post-Mutation Hooks

• Use Infection’s post-mutation scripts to analyze results:

  // infection.json
  {
    "scripts": {
      "post-mutation": "php scripts/analyze-mutants.php"
    }
  }
  

CI-Specific Reporting

• Pipe --teamcity output to CI tools:

  vendor/bin/infection --teamcity | ./node_modules/.bin/junit-report-builder -o results/
  

Tips for Laravel Developers

1. Exclude Integration Tests: Mutation testing is slow; exclude heavy integration tests:

   // infection.json
   {
     "exclude": ["tests/Integration/*"]
   }
   

2. Use Pest for Quick Feedback: If using Pest alongside Testo, prioritize Pest for fast feedback and Testo + Infection for mutation testing.

3. Monitor Testo’s Roadmap: Follow Testo’s GitHub for updates on Infection support (e.g., Laravel-specific test environments).

4. Leverage --min-detection: Start with a lower threshold (e.g., 80) to avoid false positives:

   vendor/bin/infection --min-detection=80