Download the PHP package rawphp/warp without Composer

Warp

A warm-worker test engine for Laravel + Pest.

Warp boots your Laravel application once per PHP process and hands each test a sandboxed shallow clone of it, instead of paying the full framework bootstrap (~50 ms) on every single test. Classic mode stays the default; warm mode is opt-in per run via WARP_MODE=1 and is designed to produce byte-identical outcomes to classic mode.

Host-app path: Getting started

Scope (product boundary)

Warp is a test-acceleration stack for Laravel + Pest, not a general test framework or CI platform. The package stops at the three surfaces already shipped. New work should deepen these jobs — not add adjacent products under the same name.

Warp is

Hard invariants (do not trade these away):

• Classic default — with Warp flags unset, host suite behaviour is unchanged.
• Parity first — warm mode aims for byte-identical outcomes to classic; speed is the benefit, not a licence to diverge.
• Opt-in stages — warm, snapshot DB, and timings are independent switches; none is mandatory to install the package.
• Host owns the app — Illuminate comes from the consuming app (or Testbench in Warp’s own suite); Warp is not a mini-framework.

Warp is not

These belong elsewhere (another package, the host app, Pest/PHPUnit, or CI vendor tooling). Do not grow them into this repository without an explicit product decision to split packages:

• A Pest or PHPUnit replacement — Warp plugs into them; it does not reimplement runners, assertions, or the DSL.
• A general parallel test runner — use Pest/paratest; Warp warms and provisions inside those workers.
• A full test orchestrator / daemon — no long-lived warp test scheduler, worker pool manager, or job queue.
• Result / test-impact cache — no content-addressed skip of tests from coverage maps, local memoization of pass/fail, or remote shared result cache.
• Change-based test selection — no git-diff → “run only these tests” engine.
• Flake quarantine / flake ledger product — isolation and hermeticity stay; auto-rerun policies and quarantine lanes do not.
• Generic MySQL or container ops — snapshot DB exists only to make Laravel test workers cheap and isolated, not as a DBaaS or docker-compose substitute.
• App-specific test helpers — domain factories, fakes, and suite conventions stay in the host app; Warp exposes reset/extension points instead.
• Cross-framework support — Laravel + Pest (and PHPUnit extension points Pest already uses). Not Symfony, not plain PHPUnit apps as a first-class product line.

Internal design notes may sketch later stages (see docs/specs/). Sketches are not the product boundary. Until something is listed under Warp is above (and shipped behind an opt-in flag), it is out of scope for this package.

Measured results

Measured on YardPilot's tests/Feature/Quotes suite (1,372 DB-backed tests):

Measured on a large suite (18,921 tests, 12 parallel processes):

2.55× speedup, 60.8% reduction, 487.9s saved per run. The classic run's single failure was a timing assertion that blew out under the slower run — warm mode's run had zero failures, which illustrates a secondary benefit: warm mode eliminates timing-based test flakiness caused by slow cold-boot runs.

See docs/reports/2026-07-04-s1-gate.md for the full gate report and docs/specs/2026-07-04-warp-test-engine-design.md for the design.

Requirements

• PHP 8.4+
• Laravel 13, Pest 4 (provided by the consuming app — Warp itself requires only php)

Warp's composer.json requires only php; every Illuminate class comes from the app that installs it (or from orchestra/testbench in Warp's own suite). This guarantees zero version conflicts when path-installed into a host app.

Installation

User documentation

Task-based guides for install, concepts, commands, configuration, and troubleshooting:

• docs/README.md — documentation index
• Getting started — trait wiring, classic then warm
• Concepts — classic vs warm, sandbox, resets, parity
• Usage and commands — Pest, env flags, bin/warp, CI sharding
• Configuration — ResetManifest, warp.db.*, timings
• Troubleshooting — symptom → cause → fix

Design specs and gate reports remain under docs/reports/.

Usage

1. Add the trait to your base TestCase

Current Laravel already implements createApplication() on Illuminate\Foundation\Testing\TestCase. Warp’s trait overrides that method and needs a cold-boot hook: implement createClassicApplication() by delegating to the parent (the usual path for an empty host TestCase):

That's the whole integration. With WARP_MODE unset, the trait calls createClassicApplication() every time (classic behaviour). If you still ship a custom createApplication() on the class, move that body into createClassicApplication() instead of keeping both (see Getting started).

2. Run the suite warm

With Pest's --parallel, every paratest worker becomes warm automatically.

3. Customise the reset manifest (when needed)

A shallow clone of the application shares boot-resolved singletons between sandboxes. The ResetManifest handles them declaratively; ResetManifest::default() covers Laravel's own stateful services. Override warpResetManifest() to add app-specific ones:

ResetManifest primitives:

4. Escape hatch — force a classic boot

Some tests genuinely can't share a warm base. Opt them out and Warp gives them a fresh cold boot (and skips the hermeticity check):

or per-test with a Pest group:

Snapshot DB provisioning (S2)

WARP_DB=1 replaces the per-worker migrate:fresh/schema-load fixed cost with an instant copy-on-write clone of a golden datadir — a fully migrated MySQL data directory built once per schema change and cached under .warp/snapshots/ (add .warp/ to your app's .gitignore). Each worker gets its own throwaway mysqld on a private unix socket, so parallel workers can't collide by construction.

Requirements: MySQL 8 binaries on the machine (mysqld + mysqladmin; Homebrew, apt, or point WARP_DB_MYSQLD at one) and a mysql-driver test connection. Per-test isolation is unchanged — RefreshDatabase transaction-wraps as before; the golden snapshot just makes its migrate step a no-op.

Host wiring (required): the golden build runs as a subprocess with DB_CONNECTION, DB_SOCKET, DB_DATABASE, DB_USERNAME, and DB_PASSWORD injected into its env, pointed at the golden build mysqld. Other parent DB_* values (for example DB_HOST / DB_PORT) are inherited unless overridden in warp.db.build_env. Your test connection config must read the socket from that env var:

Without it, the build subprocess falls back to whatever socket your driver defaults to instead of the per-worker one warp provisioned — this can silently target the wrong database in a single process, and fails outright (SQLSTATE[HY000] [2002] No such file or directory) under --parallel.

Optional config, all under config('warp.db'):

Tests that must commit (DDL, multi-connection assertions) can call $this->warpRecycleDatabase() for a fresh committed state via a sub-second re-clone from golden.

Timing capture + duration-balanced CI sharding (S3)

At 100k tests, count-based CI sharding leaves minutes on the table: shards get equal file counts but wildly unequal durations, and the run is as slow as the unluckiest shard. Warp records real per-test durations and packs shards to equal time instead — shard spread collapses to the mean.

1. Register the timing extension (one-time)

The extension is a no-op unless WARP_TIMINGS is set — with it unset, behaviour is byte-identical to before.

2. Record timings on full runs

Every test's duration lands in .warp/timings/ (override with WARP_TIMINGS_DIR), keyed per test with file attribution. Parallel workers write lock-free pending batches; warp merge is the explicit compaction step that folds them into timings.json. Run it once after recording, before persisting .warp/timings/ as a CI artifact/cache, and refresh that artifact on scheduled full runs. Record on full runs so every file gets measured weight. Method --filter runs upsert only (sibling test ids are retained): a file’s prior entries are superseded only when that file finished completely — every enumerated test terminated in that process.

Canonical root. Timing keys are anchored to the directory of the phpunit.xml actually used (its --configuration value, or the auto-discovered config), not to the working directory the run was launched from. This is the same root warp shard resolves discovered files against, so recording with pest -c sub/phpunit.xml from a parent directory and sharding with warp shard N/M --configuration=sub/phpunit.xml from that same parent produce intersecting keys. Only pure CLI-path runs with no XML config fall back to the current directory. The canonical root is stamped (absolute, realpath'd) into timings.json and every pending batch, and warp shard fails loudly (non-zero exit, naming both roots) rather than silently degrading if the artifact's root does not match the shard-time root.

warp shard and warp timings are read-only: they overlay pending batches in memory and do not rewrite the artifact, so read-only CI artifact restores are supported. WARP_TIMINGS_DIR is honored by every timing subcommand (merge, shard, and timings); pass --timings-dir=DIR when a command needs an explicit override. Inspect any time with:

3. Shard CI by duration

With no path arguments, warp shard discovers tests from phpunit.xml or phpunit.xml.dist testsuites, including configured directories, files, suffixes, prefixes, and excludes. Use --configuration=path/to/phpunit.xml to point at a non-default config. If no PHPUnit config exists, Warp falls back to tests/ discovery with the Test.php suffix; pass paths explicitly or use --suffix= to change that fallback.

warp shard weighs each discovered file by recorded duration (unmeasured files get the average) and LPT-packs them into equal-duration bins. Timing keys are paths relative to the canonical root — the phpunit.xml directory (see Record timings) — so tests, ./tests, and absolute paths inside the config root resolve to the same shard plan. The printed shard paths are relative to that same root, so they are directly runnable by PHPUnit/Pest when you invoke it from the same working directory with the same --configuration value you passed to warp shard. All CI nodes for a run must use the same Warp version: mixed versions across the canonical-key format change can compute divergent plans. Restore the same timings artifact on every shard of a run; if its stamped root does not match the shard-time root (for example, a --configuration pointing at a different config directory than the one recorded against), warp shard exits non-zero and names both roots instead of silently falling back to count-balanced.

With no timings recorded it degrades gracefully to count-balanced sharding (warning on stderr; stdout stays clean for $( ) consumption). Shard exit codes are:

Use an exit-code-aware guard under sh -e; this exact contract is exercised by Warp's integration suite:

Pre-UR-011 timing artifacts are a clean break: delete old .warp/timings/ contents, record a fresh full run, run warp merge, and persist the new artifact.

How it works

• WarmApplicationFactory boots the base app once per process and hands each test a shallow clone with fresh container/config anchors. The container's bindings/instances arrays are copied by value, so anything a test binds or resolves dies with its sandbox. Boot-resolved singletons shared by reference are handled by the manifest. The base's db manager is shared across sandboxes, keeping RefreshDatabase's migrate-once + per-test transaction model intact.
• ResetManifest — the data-driven reset applied to every sandbox.

• HermeticitySentinel fingerprints env vars, the base config hash, and a static-probe registry after every test. If a test leaks shared state, the sentinel fails that test with attribution:

  A leak that corrupts the base scraps it, so the next test reboots pristine. This is the correctness backstop that lets warm mode stay honest.

Public API

Benchmarks

The gate harness lives under bench/:

Development

Status

The warm-worker model is proven on real Laravel suites, from a few thousand tests up to large parallel runs. See the gate report for full methodology and results.