Pest Plugin Parallel Laravel Package

Getting Started

Install the plugin via Composer: composer require pestphp/pest-plugin-parallel --dev. Run your tests with pest --parallel—no configuration required. By default, it spawns one process per CPU core and splits test files evenly. Your first real-world use case: running a 5-minute Laravel feature test suite down to ~1.5 minutes in CI, especially for I/O-heavy or database-bound tests. Just run php artisan test --parallel (Laravel) or pest --parallel (plain Pest) in your terminal.

Implementation Patterns

• Granular control: Use --steps=N to specify how many batches to split tests into (e.g., --steps=3 for 3 runners), helpful when test files vary widely in runtime.
• Laravel integration: Leverage php artisan test --parallel—Laravel automatically handles DB connection isolation (each process gets a unique DB_CONNECTION suffix like testing-1, testing-2) and environment cleanup.
• Event-driven customization: In Laravel, listen to Pest\Parallel\Events\JobStarted or JobFinished to add logging, metrics, or bootstrap logic (e.g., seeding per-process test databases).
• Local debugging: Set PARALLEL_TESTS=1 as an environment variable to force single-process execution while keeping other --parallel flags intact.

Gotchas and Tips

• Flaky test diagnosis: Failures only sometimes reproduce in parallel often indicate shared state. Add --stop-on-failure to catch the first issue, then re-run that single test file with pest path/to/file_test.php to debug.
• Database isolation: --parallel doesn’t auto-isolate DB state—ensure you’re using Laravel’s RefreshDatabase (not DatabaseTransactions) or manually set DB_CONNECTION=testing-{$processId}.
• Coverage pitfalls: Coverage tools like Xdebug/XHProf may interfere with parallelism or produce corrupted reports. Prefer pcov (e.g., pest --parallel --coverage --coverage-driver=pcov) or avoid coverage in CI parallel runs.
• Global state red flags: Any use of putenv(), static properties, or file-based caches (e.g., without unique per-process paths like /tmp/pest-$$-cache) will cause race conditions. Always scope globals to $_SERVER, process-specific temp directories, or use dependency injection.