Abstract Testframework Adapter Laravel Package

Getting Started

Start by installing the package via Composer:

composer require infection/abstract-testframework-adapter

This package is not meant to be used directly by end-users—it’s a dependency for framework-specific Infection adapters (e.g., infection/PHPUnit-adapter). As a developer, you’ll leverage it when building or extending an Infection adapter for a new or modified test framework. The first place to look is the src/ directory—focus on:

• TestFrameworkAdapterInterface (core contract)
• AbstractTestFrameworkAdapter (base implementation)
• Configuration/ (config utilities)
• New: HasSyntaxErrorDetection interface (added in 0.5.0) for handling syntax error output.

Your initial use case will involve implementing runTests() and handling standardized results, now with optional syntax error detection via the new interface.

Implementation Patterns

• Inherit AbstractTestFrameworkAdapter: Extend the base class to avoid reimplementing common logic (e.g., argument building, exit code mapping, temporary file management).
• Implement TestFrameworkAdapterInterface: Conform to contracts like getName(), getVersion(), and runTests(): iterable|TestResult[] to ensure compatibility with Infection’s engine.
• Use shared utilities: Leverage ConfigBuilder for CLI args, TemporaryFileHelper for temp files, and Filter utilities for processing files/test suites.
• Adopt HasSyntaxErrorDetection (new): Implement the optional hasSyntaxError() method to parse and flag syntax errors in test output. Useful for frameworks where syntax failures (e.g., ParseError) should be treated distinctly from test failures.
• Separate concerns: Isolate framework-specific logic (e.g., PHPUnit’s XML config vs. Pest’s inline syntax) in adapter classes, while the base adapter handles high-level flow (prepare → execute → parse → report).
• Plugin with Infection: Register your adapter in infection.json via the testFramework config key and wire it through Infection’s DI container.

Gotchas and Tips

• Don’t expose framework internals: Keep implementation details (e.g., PHPUnit runner classes) strictly inside the adapter—never pollute the abstract layer or core Infection engine.
• Exit code mapping matters: Normalize exit codes for mutation testing; override mapExitCode() to handle framework-specific codes (e.g., syntax errors vs. test failures).
• Syntax error detection (new): The HasSyntaxErrorDetection interface expects you to parse output for syntax errors (e.g., ParseError in PHPUnit). Return true in hasSyntaxError() if the test output contains such errors. Note: This is optional but recommended for frameworks where syntax failures are critical.
• Parallelization hazards: The adapter doesn’t handle parallelism—implement it yourself only if the framework supports safe concurrent execution. Otherwise, default to sequential runs to avoid flaky tests.
• Result parsing fragility: Frameworks often change output formats (e.g., PHPUnit 9.6 → 10+). Use version sniffing via getVersion() and branch parsing logic accordingly. For syntax errors, check for framework-specific patterns (e.g., ParseError in PHPUnit’s JSON output).
• Tested abstractly: This package has no real tests itself (stars: 25). Verify your adapter’s correctness in a separate project with real test suites. Use AbstractTestFrameworkAdapter::getTests() as the canonical reference for output expectations.
• Extensibility points: Override getAdditionalArguments() for framework-specific CLI flags and createProcess() to inject custom process behavior (e.g., env vars, timeouts). For syntax errors, extend hasSyntaxError() to handle edge cases (e.g., suppressed errors).