Paratest Laravel Package

Product Decisions This Supports

• Developer throughput vs. infrastructure spend. Test-suite wall-clock time is a direct tax on every PR and every CI run. ParaTest is a one-line, MIT-licensed lever that turns "our suite takes 12 minutes" into a capacity-planning conversation (add CI runners vs. add parallelism) with a near-zero integration cost. It informs whether we buy more CI minutes or spend an afternoon on a composer require --dev.
• Build vs. buy on test infrastructure. ParaTest deliberately depends on PHPUnit @internal classes to avoid re-implementing the runner. That is the classic "don't build it" argument: any in-house parallel test harness we write becomes a permanent maintenance liability against a moving PHPUnit target. Adopt and contribute upstream instead of owning worker orchestration, result-file merging, and coverage aggregation ourselves.
• Feature and roadmap sequencing: test independence as a prerequisite, not a nice-to-have. ParaTest's documented caveats (no shared statics/constants/reflection across test classes; per-process initialization via flock) surface latent test pollution. Deciding to adopt it is really a decision to fund a test-isolation cleanup — and to stop accepting PRs that introduce cross-test global state.
• CI topology decisions. The --shard option (v7.13) plus --functional mode gives us a choice between vertical parallelism (more workers on one node) and horizontal sharding across a matrix. That's a cost/latency trade-off we can now measure rather than guess at.
• Coverage as a gate, not an afterthought. Parallel runs merge coverage into a single report (PCOV, Xdebug, OpenClover, --exclude-source-from-xml-coverage). This unblocks enforcing coverage thresholds in CI without running the suite twice or serially.
• Local dev experience. The paratest_for_phpstorm binary plus "Rerun failed tests" support means faster inner-loop feedback without asking engineers to change how they run tests. Good DX spend with measurable effect on PR size and review latency.
• Prioritizing the PHPUnit upgrade backlog. ParaTest supports only the latest PHPUnit and PHP releases. Adopting it converts a vague "we should upgrade PHPUnit someday" into a scheduled dependency: every PHPUnit major is now a hard deadline for the test-infra owner.
• Concrete use cases: large monorepo suites, per-process database isolation via TEST_TOKEN/UNIQUE_TEST_TOKEN, enforcing time limits per test (--enforce-time-limit), TestDox text/HTML reporting for stakeholder-facing test summaries, and detecting worker crashes before result files are written (v7.16.1) so flaky infrastructure doesn't masquerade as green builds.

When to Consider This Package

Adopt when:

• The project runs on PHPUnit (directly, or via Laravel's php artisan test --parallel or Pest's parallel plugin — both of which sit on top of ParaTest, so the real decision is often already made for you).
• The suite has grown past roughly 1–2 minutes of serial runtime; below that, parallelism overhead and added nondeterminism aren't worth it.
• Tests are already reasonably independent, or the team is willing to make them so — per-process databases via TEST_TOKEN are the typical first fix.
• CI has spare CPU or the budget to add it; parallelism without cores just adds contention.
• The team can commit to tracking the latest PHPUnit major, since ParaTest only supports the newest version and is maintained against it.

Look elsewhere or defer when:

• The project is pinned to an older PHPUnit/PHP version. There is no LTS path here — the maintainers are explicit that only the latest is supported, so adopting it is a forward-pressure commitment.
• Tests rely heavily on shared statics, constants, or reflection across test classes — ParaTest's WrapperRunner explicitly does not support this, and the fix (extract shared code out of test classes) can be a large refactor.
• Setup code assumes "run exactly once per invocation" semantics; the documented flock/touch lock-file pattern has to be adopted deliberately rather than discovered in a flaky CI run.
• The framework isn't PHPUnit-family (Codeception, PHPSpec, Behat) — out of scope.
• CI is a single low-core runner, or the pipeline is already dominated by build/install steps rather than test execution.
• Strict determinism is a hard requirement (e.g., ordered integration suites) — parallelism trades some reproducibility for speed, and parallel-only failures are a real debugging cost to budget for.

Metadata caveat worth flagging: ParaTest is a dev-dependency, not a runtime library, so registry "dependents" counts systematically understate its real footprint. The better adoption signal is that major frameworks wrap it; the ~2.5k stars reflect the maintainer-facing audience, not end-user reach. Judge it on ecosystem coupling and release cadence (frequent, version-pinned releases tracking PHPUnit 12 and PHP 8.5), not star count.

How to Pitch It (Stakeholders)

To executives: ParaTest is a free, MIT-licensed, drop-in parallel test runner for our PHP stack. Installation is a single dev dependency with no configuration, it's reversible in one commit, and it typically cuts CI test time roughly in proportion to available cores. It directly reduces the two costs leadership feels most: PR cycle time and CI spend. The primary strategic cost is a standing commitment to keep PHPUnit current — treat that as a scheduled maintenance line item, not a surprise. Recommended: adopt on one high-traffic repository, measure suite runtime and CI cost for two weeks, then decide on broader rollout.

To engineering leadership and platform teams: It's the de facto standard parallel runner for PHPUnit, and it's the engine underneath Laravel's and Pest's built-in parallel testing — meaning we're likely already transitively dependent on it. We get combined coverage reports, sharding across CI nodes, per-worker database isolation via TEST_TOKEN, time-limit enforcement, and a PHPStorm helper for local runs. Known constraints are well-documented and manageable: no shared statics or reflection across test classes, and per-process initialization needs an explicit file-lock pattern. There is a real onboarding cost in fixing test pollution; that work is valuable independent of the tool.

To the engineering team: Install with composer require --dev brianium/paratest, run vendor/bin/paratest to parallelize by TestCase or --functional to parallelize by individual test. Before rollout: audit for shared static state and cross-test class coupling, switch per-process databases to TEST_TOKEN, adopt the documented lock-file pattern for one-time setup, and enable --verbose when triaging subprocess failures (the failing command is printed and can be copy-pasted). Plan a short burn-in period where parallel-only failures are triaged rather than retried.