Paraunit Laravel Package

Product Decisions This Supports

• CI cost vs. developer velocity trade-off. Paraunit runs PHPUnit test classes across multiple parallel PHPUnit processes (vendor/bin/paraunit run), so the decision "do we buy more CI runners or make the suite faster?" can be answered with a cheap dev-dependency trial instead of a spend increase. If the suite is class-parallelizable, wall-clock time drops roughly with core count — the same effect as sharding, without writing shard logic.
• Whether to gate merges on full-suite runs. Teams often skip pre-merge full runs because feedback takes too long. A faster suite changes the policy decision: full suite on every PR becomes viable, which in turn affects review latency and defect-escape rate targets.
• Whether coverage becomes a real quality metric. Parallel coverage collection (vendor/bin/paraunit coverage --html=./dir, plus Clover/Cobertura/XML/text) with automatic driver selection (Pcov → Xdebug → PHPDbg) makes coverage practical on a slow suite. This directly supports decisions about coverage thresholds, coverage-diff bots, and GitLab MR coverage visualization (Cobertura output exists specifically for this).
• Build vs. buy vs. DIY sharding. The alternatives are: (a) hand-rolled CI matrix sharding in the pipeline config, (b) migrating to a framework with native parallelism (Pest --parallel), (c) adopting Paraunit, (d) doing nothing. Paraunit is the lowest-effort option when the stack is vanilla PHPUnit on Symfony, and it keeps the existing runner and config.
• Roadmap sequencing for a platform/DevEx workstream. If "reduce test feedback time" is a candidate roadmap item, Paraunit is a spike-sized experiment (hours, not sprints) that produces a measurable number to justify or kill the larger initiative.
• Monorepo / test-suite consolidation calls. --exclude-testsuite, --test-suffix, --chunk-size, and --sort=random (flaky-order detection) support decisions about how many test suites to maintain and whether ordering-dependent tests are safe to combine.
• Local vs. CI parity. Because it is a Composer dev dependency with a bin launcher and mirrors PHPUnit's own flags (--stop-on-*, display-warning/deprecation options, --pass-through), the same command can be used locally and in CI — a single documented workflow rather than two.

When to Consider This Package

Adopt when most of these hold:

• Suite runtime is a felt pain: roughly 5+ minutes serial, many test classes (parallelism is per class/file, not per test method), and CI runners with multiple cores already paid for.
• PHPUnit 10.5.4+ through 13 and PHP 8.1+, Symfony 4.4–8 — the compatibility matrix is current and actively maintained against new PHPUnit majors.
• Test classes are independent: no shared mutable fixtures, no fixed ports, no cross-class ordering assumptions, no single shared database without per-process isolation.
• The team accepts one committed config change: since 2.0, Paraunit needs a bootstrap extension registered in phpunit.xml (it offers to add it on first run). This is a reviewed, committed change to shared test config — treat it as a governance item, not a local tweak.
• You want coverage from the same tool rather than bolting on a second pipeline step.

Look elsewhere, or fix preconditions first, when:

• The suite is small/fast (sub-2-minute) — the added process orchestration and config surface is not worth it.
• Tests are not isolation-safe. Parallelism amplifies shared-state bugs into intermittent, hard-to-triage CI failures. Run --sort=random serially first, or budget time for a test-isolation cleanup as part of the adoption.
• You need per-test-method parallelism or a mature, widely adopted ecosystem: Paratest is the better-known incumbent with a larger user base — evaluate it head-to-head rather than defaulting.
• You are on Pest or another runner with native parallelism — use the built-in.
• You need strong maintenance/support guarantees. Signals here are thin: ~145 stars, 0 listed dependents, single-vendor (facile-it) stewardship, no PHAR distribution. It is a healthy-looking, actively released Apache-2.0 project (recent releases, changelog discipline, broad PHPUnit/Symfony matrix), but the bus factor and third-party adoption evidence are weak. For a low-risk dev-only dependency that's acceptable; do not let it become load-bearing infrastructure you can't replace in a day.
• Windows-based local dev without ext-pcntl — the requirement was downgraded to "suggested" in 2.11.0, but validate actual behavior on your target platforms before standardizing the command.

How to Pitch It (Stakeholders)

For executives (one paragraph): Our test suite is a tax on every change we ship — it slows PR review, discourages full-suite runs before merge, and makes coverage reporting expensive. Paraunit is a free, Apache-2.0, Composer-installed dev tool that runs our existing PHPUnit tests in parallel across available CPU cores, and collects coverage in parallel too. It requires no application code changes and no new infrastructure — it reuses the PHPUnit config we already have, with one small committed config addition. The ask is a timeboxed spike on one repository: measure before/after suite duration and CI minutes. If the numbers don't move, we uninstall it and lose a day. If they do, we get faster feedback and lower CI spend for the cost of a dev dependency.

For engineering leads: This is a drop-in runner (vendor/bin/paraunit run, vendor/bin/paraunit coverage --html=...), compatible with our PHPUnit 10.5.4+/11/12/13 and Symfony versions, and it mirrors PHPUnit's flags so existing muscle memory and CI scripts carry over (--stop-on-*, deprecation/warning display, --pass-through, --chunk-size). It is maintained, released regularly, and tracks new PHPUnit majors promptly. The real prerequisite is test isolation, not tooling: we must confirm classes don't share state, ports, or DB fixtures. Note it's a niche project (~145 stars, no tracked downstream dependents, single-vendor), so scope it as a replaceable developer convenience — not a platform commitment — with Paratest as the fallback comparison.