Weave Code
Paraunit Laravel Package
facile-it/paraunit
Paraunit speeds up PHPUnit test suites by running tests in parallel across multiple PHPUnit processes. Built on Symfony components, it can collect coverage in parallel and supports many PHPUnit and Symfony versions. Install it via Composer as a dev dependency.
Paraunit is a tool for faster execution of PHPUnit test suites, launching multiple tests in parallel across separate PHPUnit processes. Built on Symfony components, it runs as a console command via vendor/bin/paraunit run, executing all tests in your configured suites.
- Parallel test execution for significantly faster suites
- Parallel coverage collection with automatic best-driver detection (Pcov, Xdebug, phpdbg)
- Broad compatibility across PHPUnit 10–13 and Symfony 4.4–8
- Simple install via
composer require --dev facile-it/paraunit
Frequently asked questions about Paraunit
- How do I install facile-it/paraunit in a Laravel project?
- Install it as a dev dependency with Composer using composer require --dev facile-it/paraunit. Then run your Laravel test suite through vendor/bin/paraunit run instead of the normal PHPUnit command. Paraunit is designed as a drop-in parallel runner for PHPUnit-based suites, so it does not require changes to Laravel core or your application testing libraries.
- Does Paraunit work with Laravel's PHPUnit test suite?
- Yes, Paraunit is a strong fit for Laravel applications that use PHPUnit because it launches multiple PHPUnit processes in parallel. Laravel's Console and dependency injection layers remain compatible with Paraunit's Symfony-based command structure. Tests that depend on shared database state or global state still need isolation, just as with any parallel test runner.
- Which PHPUnit versions are compatible with Paraunit for Laravel projects?
- Current Paraunit 2.x releases require PHPUnit 10.5.4 or newer, and the compatibility table lists support for PHPUnit 10.5.4+, 11+, 12+, and 13.0 depending on the Paraunit version. Paraunit 2.8 supports PHPUnit 10.5.4+, 11+, 12+, and 13.0. If you plan to use JSONL coverage, you also need phpunit/php-code-coverage 14.4 or newer.
- How do I collect code coverage in parallel with Paraunit?
- Use the coverage command, for example vendor/bin/paraunit coverage --html=./dir, to collect coverage while running tests in parallel. Paraunit automatically tries to use the best available coverage driver among Pcov, Xdebug, and PHPDbg. For CI pipelines that can ingest JSON Lines, newer releases support JSONL coverage, but teams standardized on Cobertura or HTML should keep those formats as their primary output.
- What is --pass-through in Paraunit and can I pass --timeout to PHPUnit?
- The --pass-through option in Paraunit 2.13.0 and later forwards additional PHPUnit CLI flags through to the underlying PHPUnit processes. This includes flags such as --timeout, --cache-test-index, and --do-not-cache-test-index. It improves parity with PHPUnit and reduces the need for custom wrapper scripts when you need timeout control or test-index caching.
- Should I use --cache-test-index with Paraunit in Laravel CI?
- Test-index caching can improve startup time for large Laravel test suites, but cached indexes can become stale if they are reused across changed branches or shared CI caches. Scope the cache by branch or commit, or use --do-not-cache-test-index in clean and deterministic CI jobs. Treat the cache as an optimization that must be invalidated carefully rather than a permanent artifact.
- What --timeout value is safe for parallel Laravel tests with Paraunit?
- There is no universal safe value because parallel execution can put more load on CI runners than a serial run. Tune the timeout against your worst-case CI load and document standard values for the team. Very low timeout values may cause false failures under parallel load, so validate changes against realistic CI conditions.
- Does Paraunit's JSONL coverage replace Cobertura or HTML coverage?
- No, JSONL coverage is an additional machine-readable output format and mirrors PHPUnit's coverage-jsonl support. It requires phpunit/php-code-coverage 14.4 or newer and is useful only when your CI and reporting tools can parse JSON Lines. Keep Cobertura or HTML as a fallback unless you have validated that your downstream tooling supports JSONL.
- What are common Laravel issues when running tests in parallel with Paraunit?
- The main risks are database transaction conflicts, shared application state, race conditions, and tests that are not isolated from each other. Use test isolation, separate test databases or transactions where appropriate, and exclude stateful tests that cannot run safely in parallel. Options such as --stop-on-failure, --debug, and --chunk-size can help diagnose and contain parallel-specific failures.
- How do I debug parallel-only test failures in Paraunit?
- Start by rerunning the failing subset or reducing the chunk size so fewer tests execute at once. Use --stop-on-failure and --debug to get clearer failure output, and check for shared state, stale test-index caches, or timeouts that only appear under parallel load. If coverage is involved, confirm the coverage driver and output format are compatible with your PHPUnit and phpunit/php-code-coverage versions.
Weaver
How can I help you explore Laravel packages today?