Paraunit Laravel Package

Getting Started

Paraunit is a drop-in replacement for PHPUnit designed to speed up test suite execution via parallelization. To begin:

1. Install via Composer: composer require --dev facile-it/paraunit
2. Run tests: vendor/bin/paraunit run
3. For initial use, Paraunit will automatically propose adding its PHPUnit bootstrap extension if missing (required for PHPUnit 10+); accept unless you prefer manual config.

Start with the basic run command. It discovers and runs all tests from your phpunit.xml configuration, respecting test suites, filters, and timeouts — just like plain PHPUnit, but faster. Coverage collection is also supported out-of-the-box: vendor/bin/paraunit coverage --html=coverage.

Implementation Patterns

• Drop-in Replacement: Use Paraunit in CI pipelines instead of phpunit with minimal changes. Drop in vendor/bin/paraunit for vendor/bin/phpunit in scripts or Composer scripts.
• Chunking for Large Suites: For slow test suites, use --chunk-size=N to batch tests into N parallel workers, reducing memory pressure and improving fairness in worker load.
• Test Filtering with Flags: Combine --testsuite=unit,integration, --exclude-testsuite=slow, --test-suffix=.test.php, or --sort=random to control execution patterns while retaining parallel speed.
• Coverage Workflow: Paraunit auto-selects the best coverage driver (pcov > xdebug > phpdbg). Generate diverse reports (--cobertura, --clover, --html) for integration with tools like GitLab, SonarQube, or CI dashboards.
• Debugging: Use -vvv to see full subprocess output, aiding in diagnosing failing tests in parallel runs. For flaky tests, temporarily disable parallelization (--processes=1) to reproduce issues.
• Notices as Test Issues: As of v2.8.0, notices (e.g., E_USER_NOTICE, deprecations) are surfaced as distinct test issues alongside failures and errors. This improves visibility into soft failures without breaking the build; use --fail-on-notices to enforce strict failure conditions.

Gotchas and Tips

• PHPUnit Extension Requirement: Paraunit 2.x requires its extension in phpunit.xml (auto-added on first run). If tests fail silently, verify the <extension class="Paraunit\Extension\ParaunitExtension" /> line exists.
• Coverage Artifacts: Coverage data is collected per-process and merged. Ensure your coverage output directory has write permissions. Avoid overlapping paths with existing PHPUnit coverage runs (don’t mix phpunit --coverage and paraunit coverage without cleanup).
• Environment Leaks: Because tests run in separate processes, avoid relying on shared static state or environment variables unless explicitly reset per-process. Use setUpBeforeClass() and tearDownAfterClass() with caution — they run per-process, not per-class globally.
• Output Capture: Output (e.g., echo, dump) may interleave unpredictably in parallel runs. Prefer assertions over stdout. Use --debug to associate output with specific tests when debugging.
• Retryable Exceptions: Paraunit includes built-in retry logic for known transient DB issues (e.g., MySQL deadlock). For PostgreSQL, enable --detect-deadlocks and review your transaction boundaries.
• Custom Options Passing: Use --pass-through="option=value" to forward raw PHPUnit CLI flags unsupported by Paraunit directly — e.g., --pass-through="--convert-deprecation-to-exceptions".
• Symfony 8 + PHPUnit 13: Paraunit v2.8.0+ supports PHPUnit 13. Ensure your phpunit.xml respects updated event system requirements — the bootstrap extension remains mandatory.
• Notices Handling: Since v2.8.0, warnings and notices can affect exit codes and reporting if not accounted for. Verify test suites expecting silent notices aren’t silently breaking expectations — consider using --fail-on-notices=false during transition.