Paraunit Laravel Package

Technical Evaluation

Architecture fit (against a Laravel codebase)

• Paraunit is a PHPUnit orchestration layer, not a Laravel package: it is a Symfony Console application distributed as a Composer dev dependency, invoked as vendor/bin/paraunit run. There is no service provider, no Artisan command, no config/ publish, and no awareness of Laravel's ParallelTesting machinery. Architecturally it sits below Laravel's own test tooling.
• Because it spawns raw PHPUnit child processes, it bypasses php artisan test --parallel (Laravel's Paratest-based wrapper) and therefore bypasses Laravel's per-process test-database provisioning (ParallelTesting::setUpTestDatabase, TestDatabases / DatabaseMigrations traits, ParallelTesting::setUpProcess callbacks). Any DB, cache, queue, or filesystem isolation that artisan test --parallel gives us for free must be rebuilt for Paraunit runs.
• Since 2.0 the PHPUnit integration mechanic changed to PHPUnit's event system, requiring a bootstrap extension registered in the PHPUnit XML config. On first run without it, Paraunit prompts to add it automatically. That means a committed, shared phpunit.xml gets mutated — a config file that developers, CI, and artisan test all read.
• Coverage collection is parallelized natively, auto-selecting Pcov → Xdebug → PHPDbg, with HTML/Clover/Cobertura/XML/Crap4j/PHP/text output. This is the one capability where Paraunit offers something Laravel's --coverage path does not parallelize cleanly.

Integration feasibility

• Mechanically trivial: one composer require --dev facile-it/paraunit, one binary, one PHPUnit config addition. Low engineering effort, no application-code changes.
• The compatibility matrix is current and relevant: Paraunit 2.8 covers PHPUnit 10.5.4+/11/12/13 and Symfony 4.4–8, with PHPUnit 12, PHP 8.4, and Symfony 8 support landed in 2.5–2.8. That aligns with Laravel 10/11/12-era PHPUnit versions.
• The genuinely hard part is test isolation semantics, not installation. Laravel feature/integration tests commonly share a database, Redis, storage disks, and global helpers; correctness under N concurrent processes is a property of our suite, not of Paraunit.

Technical risk

Key questions

1. Does Paraunit propagate phpunit.xml <php>/<env> blocks and env vars to child processes exactly as PHPUnit does? Laravel's test config depends on this.
2. Is a per-process identifier (e.g. TEST_TOKEN) injected into children, or must DB isolation be solved by the bootstrap extension / --pass-through? Without this, DB-per-process isolation is bespoke work.
3. Can the bootstrap extension be scoped to a separate XML config file so artisan test and IDE test runners remain untouched?
4. Does it emit per-process JUnit logs, or a merged report? What is the CI parsing story versus Paratest's single merged JUnit?
5. What are the exact exit-code and --stop-on-* semantics when defects occur in different parallel processes (fail-fast correctness for PR gates)?
6. What is the maintainer's stated roadmap/cadence for PHPUnit 14 and new Laravel majors, and is commercial support available?
7. Recommended process-count and --chunk-size heuristics for Laravel-sized suites, and memory ceiling per worker?

Integration Approach

Stack fit

• Fits cleanly at the tooling layer: Composer dev dependency, PHP 8.1+ floor, PHPUnit 10.5.4+ — all compatible with a current Laravel 10/11/12 stack. No runtime/production footprint whatsoever.
• Poor fit at the framework-semantics layer: no Laravel ParallelTesting integration, no Artisan surface, no awareness of Laravel's per-process DB lifecycle. Treat it as a PHPUnit-level replacement for the runner, and re-implement isolation deliberately.
• Best strategic fit is CI-only, coverage-gated adoption: parallel coverage generation is a capability we do not currently have, and the CI stage is where wall-clock savings convert directly into developer throughput and cost.

Migration path

1. Baseline first. Record suite wall-clock, worker count, flake rate, and CI minutes for artisan test and artisan test --parallel. Without this the value case is unprovable.
2. Additive, non-destructive config. Create phpunit.paraunit.xml as a copy of phpunit.xml plus the Paraunit bootstrap extension; leave the canonical phpunit.xml unmodified so artisan test, IDE runners, and existing CI jobs are unaffected. Pre-provision the extension to avoid the interactive prompt.
3. Solve isolation explicitly before enabling feature/integration tests: per-worker database name or schema, unique storage/cache prefixes, disabled/redirected queue and notifications, faker/unique-ID collision review.
4. Phased suite enablement. Unit-only suites first (usually already isolation-safe) → feature suites → database-heavy suites. Use --exclude-testsuite to carve out unsafe groups while the rest parallelizes.
5. Add the coverage gate using vendor/bin/paraunit coverage --cobertura=... (Cobertura is explicitly supported and GitLab-friendly) once correctness under parallelism is trusted.
6. Standardize behind a Composer script or Make target so developers and CI run the identical invocation.

Compatibility

• Pin Paraunit to a minor and treat its version as coupled to the PHPUnit version, not independently upgradable. Add a CI matrix job that runs both the Paraunit path and plain phpunit to catch bootstrap-extension regressions early.
• Validate on the exact PHP/coverage-driver combination used in CI; Pcov availability materially changes both speed and results for coverage runs.
• Verify behavior on any non-Linux developer machines, given ext-pcntl is now optional/suggested and real parallelism may depend on it.

Sequencing (by risk, not by enthusiasm)

Crucially, keep artisan test --parallel as the documented fallback at every phase so the exit cost stays near zero.

Operational Impact

Maintenance

• Ongoing effort is dominated by PHPUnit/Laravel major-version tracking, not by the package itself. Release history shows recurring compat patches immediately after PHPUnit releases; budget a small, recurring slice of platform-engineering time each upgrade cycle rather than a one-off.
• The committed bootstrap-extension reference in test configuration is a permanent, shared-file dependency. Any future cleanup of test config must account for it — a small but real piece of long-lived technical debt.
• Pin and review: because dependents are zero and the project is single-vendor, do not accept implicit "latest" resolution in CI.

Support

• Apache-2.0, public GitHub issues, no documented commercial support tier, ~145 stars, 0 dependents. Assume no external SLA. Mitigations: assign a named internal owner, pin the version, subscribe to releases, and preserve the fallback runner.
• Abandonment risk is mitigated structurally — the package is a dev-only binary with no runtime coupling, so removal is a composer remove plus a CI job revert. This is a low-blast-radius dependency.

Scaling

• Throughput is bounded by physical cores and per-worker memory, not by the tool. Laravel application boot per worker (~tens to low-hundreds of MB) sets a hard concurrency ceiling on containerized CI runners.
• Diminishing returns appear on small or I/O-bound suites where fixed boot cost dominates; largest wins are on suites with many independent, boot-heavy test classes.
• --chunk-size is the primary tuning lever; --sort=random is a useful flake-detection tool but should not be the default in the PR gate.
• Recommend starting at worker count ≈ available vCPUs (or vCPUs/2 for memory-heavy suites), then tuning against measured wall-clock rather than intuition.

Failure modes

1. New flaky failures from shared state — the highest-probability operational issue and the one most likely to erode team trust in the change. Detect via repeated-run baselining before rollout.
2. CI OOM / timeouts — N concurrent Laravel boots plus coverage driver overhead exceed runner limits; surfaces as nondeterministic job failures.
3. Coverage drift — driver auto-selection (Pcov → Xdebug → PHPDbg) means results/speed vary by environment; missing Pcov silently degrades to slower paths.
4. Bootstrap-extension incompatibility after a PHPUnit bump — can break both the Paraunit path and, if the extension is in the shared config, plain PHPUnit runs. Contained by using a separate XML config.
5. Non-interactive CI prompt on a machine without the pre-provisioned extension — hard failure at the worst moment (fresh clone, new runner image).
6. Orphaned child processes on abnormal parent termination, especially where ext-pcntl is absent; 2.7.0 improved abnormal-termination detection but process cleanup should be verified.
7. Defect attribution ambiguity — with --stop-on-* now supported, confirm fail-fast semantics across processes so PR gates fail for the right reason and reporting remains legible.

Ramp-up

• Developer learning curve is genuinely small: one new command, plus the important mental-model shift that tests must be isolation-safe. Publish a short isolation checklist (DB, cache, storage, queue, notifications, faker uniqueness, time freezing) alongside the command.
• CI/CD ramp-up is the real work: new job or job variant, coverage artifact handling, JUnit/report aggregation, runner resource sizing, and a documented rollback switch.
• Realistic adoption: a focused spike plus isolation work is a sprint-scale effort for one engineer; the recurring cost is a small maintenance tax per PHPUnit/Laravel major, offset by reduced PR feedback latency and cheaper parallel coverage.
• TPM recommendation: worth a bounded spike (Phases 0–2) if and only if measured suite duration is a top-three developer-feedback complaint. If Laravel's artisan test --parallel already meets the latency target, the incremental value reduces to parallel coverage alone — evaluate on that narrower justification, and expect the honest outcome to be "keep one parallelization story, not two."