Async Testing Laravel Package

Getting Started

• Install as a dev-only dependency: composer require --dev recca0120/async-testing. It is a test-time tool; nothing should ship in production.
• Look here first, in this order: the README, then composer.json (bin, scripts, autoload-dev), then src/ for the console command or runner class. Five minutes in src/ will tell you the exact invocation far faster than guessing. Also skim the package's own tests/ directory — its self-tests are the most reliable usage example.
• Confirm what it actually replaces. The description ("Laravel parallel") puts it in the same slot as php artisan test --parallel (Paratest) and as a wrapper around PHPUnit process spawning. Check the README for whether it is a runner binary, an artisan command, or a TestCase base class you extend — the integration path differs completely for each.
• First use case: pick a small, already-green suite where every test is independent (no test writes fixtures that another test reads). Run the package's runner against it and compare wall-clock against vendor/bin/phpunit. That baseline tells you whether process boot overhead is worth it for your suite size.
• Pin the version explicitly ("recca0120/async-testing": "x.y.*"). The last release is 2024-05-03, so verify compatibility against your Laravel and PHPUnit majors before wiring it into CI — PHPUnit 10/11 rewrote large parts of the runner API, and older parallel runners break silently there.
• Only adopt this if it gives you something Laravel's built-in parallel testing does not. For most apps on Laravel 8+, the built-in is the lower-risk default; this package earns its place when you need a different process model or lower memory per worker.

Implementation Patterns

• Baseline-then-optimize workflow. Record serial runtime first. Then enable the runner and record again, per suite. Split your suites so you can see which one actually parallelizes well — usually integration/HTTP tests do, pure unit tests don't.
• Partition deliberately. Keep a "fast" subset (unit + a handful of feature tests) for pre-commit and local loops, and reserve the parallel runner for the full suite in CI or pre-push. A 30-second suite gets slower when you spread process boot across four workers.
• Per-worker database isolation is the load-bearing pattern. Either give each worker its own schema/database (e.g. DB_DATABASE=test_${worker} derived from the worker index/token the runner exposes) or run migrations plus seeding per worker and tear down afterwards. Never let two workers share a schema.
• Force every external dependency to a deterministic, in-process driver via per-worker env: CACHE_DRIVER=array, QUEUE_CONNECTION=sync, MAIL_MAILER=array, SESSION_DRIVER=array, BROADCAST_DRIVER=null. Anything that touches a real network service will collide under parallelism.
• CI integration: run it as one job with an explicit worker count tied to available cores, and capture the exit code correctly (set -o pipefail if you tee output). Write per-worker logs to storage/logs/ so failures are readable rather than interleaved.
• Coverage: parallel runs produce fragmented coverage. Use --coverage-php per worker and merge with phpcov merge, rather than expecting a single clover file to be correct.
• Share setup through a base TestCase/trait rather than copying setUp across suites — this is also where you centralize the per-worker DB and env bootstrapping so the parallelism stays invisible to individual tests.
• Wrap the invocation in a Composer script ("test:parallel": "...") so the runner's flags and worker count live in one place instead of in every developer's shell history or CI YAML.

Gotchas and Tips

• Filesystem collisions are the #1 failure. storage/framework/{cache,sessions,views}, compiled Blade views, and log files are shared by default. Give each worker its own subdirectory keyed by worker index, or you'll get inexplicable cache and view errors that vanish on a serial re-run.
• SQLite :memory: does not work across processes. Each worker gets its own empty in-memory DB. Use a file-based SQLite database per worker, or a real server (MySQL/Postgres) with per-worker schemas.
• DDL and transactions interact badly under parallelism. If your tests wrap in transactions, ensure no worker is running migrate:fresh while another is mid-test. Parallel migration is a common source of deadlocks and flaky "table already exists" errors — migrate once up front, then fan out.
• Static and singleton state leaks between tests within a worker. Parallelism hides some ordering flakes and exposes others. If a test passes alone but fails in a run, it's shared state, not the runner.
• config:cache is a trap. A cached config file freezes env values, so per-worker overrides silently do nothing. Clear config before parallel runs, or avoid caching in test environments entirely.
• Port conflicts hit you the moment you parallelize Dusk, Selenium, or any test that boots a local HTTP server. Allocate a distinct port per worker.
• Debugging recipe: reproduce the failure with --filter on a single process first. If it passes, bisect by running with a fixed seed and reduced worker count (-j1, then -j2). The point at which it breaks tells you whether it's a DB, filesystem, or port problem.
• Env precedence is confusing: phpunit.xml <env> entries, .env.testing, and the runner's per-worker environment all compete. Know which wins in your setup — put worker-specific values in the layer that overrides last, and assert it with a one-off dd(env(...)) rather than assuming.
• Don't over-parallelize. Worker count beyond physical cores typically hurts; memory per worker (each boots a full Laravel app) is often the real ceiling, especially with Octane-sized configs.
• Maintenance risk: 63 stars, last release mid-2024. Treat it as a convenience, not infrastructure — keep the ability to fall back to php artisan test --parallel or serial PHPUnit with a one-line script change, and check the issue tracker for your PHPUnit version before adopting.