vusys / zefram
Skip PHPUnit tests whose executed code hasn't changed since they last passed. Faster than light.
Requires
- php: ^8.2
- phpunit/phpunit: ^11.5 || ^12.0 || ^13.0
Requires (Dev)
- illuminate/console: ^11.44.2 || ^12.4.1 || ^13.0
- illuminate/support: ^11.44.2 || ^12.4.1 || ^13.0
- infection/extension-installer: ^0.1.2
- infection/infection: ^0.29 || ^0.33 || ^0.34
- larastan/larastan: ^3.0
- laravel/pint: ^1.30
- orchestra/testbench: ^9.12 || ^10.1 || ^11.0
- phpstan/phpstan: ^2.2
- rector/rector: ^2.6
Suggests
- ext-pcov: Required to capture per-test coverage; without it Zefram disables itself and all tests run.
- laravel/framework: For the artisan zefram:clear / zefram:stats commands.
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v0.1.0
- dev-chore/release-0.1.0
- dev-docs/18-readme-polish
- dev-ci/68-codecov
- dev-feat/87-teardown-guard
- dev-fix/83-cache-per-config
- dev-fix/83-pcov-disabled
- dev-issue-16-gha-cache-recipe
- dev-issue-13-functional-guard
- dev-issue-12-suppress-paratest-summary
- dev-issue-11-paratest-token
- dev-issue-10-warp-factor
- dev-issue-9-stats-command
- dev-issue-8-cli-scaffold-clear
- dev-issue-7-prune-stale-records
- dev-issue-6-prune-fingerprint-dirs
- dev-issue-4-fingerprint-phpunit-xml
- dev-issue-3-isolate-e2e-suite
- dev-issue-23-e2e-generator-invalidation
- dev-issue-22-e2e-dogfood-test
- dev-issue-2-dogfood-harness
- dev-issue-1-graph-generator
This package is auto-updated.
Last update: 2026-11-16 20:54:58 UTC
README
Tests running faster than light. Zefram records the set of files each PHPUnit test executes and, on later runs, skips any test whose recorded files are all unchanged since it last passed — before your framework boots, before the database refreshes.
Status: beta, pre-1.0. Tested end-to-end by its own e2e suite (dogfooding its source, a generated dependency graph, and a real testbench Laravel app) and trialled on a 6,029-test Laravel suite under paratest: a 5:20 full run became a 12s unchanged rerun, with no false skips from code coverage can see (see #15). The configuration can still change before 1.0.
How it works
- A trait in your base TestCase overrides
setUp()and decides the skip before delegating toparent::setUp()— so a skipped test never boots Laravel, never touches the database. (A#[Before]hook can't do this: PHPUnit swallows a skip thrown there and runssetUp()anyway.) - If the test runs and passes, a PHPUnit extension records the files it executed (captured per-test via pcov) with content hashes, sharded per test class under
.zefram/. - Next run, if every recorded file hashes the same — and the global fingerprint (composer.lock, phpunit config, PHP version, watched paths) matches — the test is skipped.
Failures are never cached: only a passing run can create a skip record, and any non-pass drops it.
At the end of a run, the extension prints a summary line:
Zefram: skipped 12 of 20 tests (~4.2s at sublight, warp factor 3.1)
The warp factor is a real computed ratio, not flavor text: (the stored duration of every skipped test, from the last time it actually ran, plus the real measured duration of every test that did run this pass) ÷ (the actual wall-clock time this pass took). A run with nothing skipped sits around 1.0; heavy skipping pushes it up. It can also sit below 1.0 on a suite whose tests are already near-instant — skipping a handful of microsecond tests can't outrun fixed PHPUnit process/bootstrap overhead, and the metric says so honestly rather than flattering itself.
Installation
composer require --dev vusys/zefram
Requires PHP ≥ 8.2, PHPUnit ≥ 11.5, and pcov loaded with pcov.enabled=1. Without it, Zefram disables itself, all tests run normally, and the summary line says why.
Add the trait to your base TestCase:
abstract class TestCase extends \PHPUnit\Framework\TestCase { use \Vusys\Zefram\ZeframAware; }
If your TestCase defines its own setUp(), it takes precedence over the trait's — call the helper first thing instead:
protected function setUp(): void { $this->zeframSetUp(); parent::setUp(); // your setup }
A skipped test never reaches parent::setUp(), but PHPUnit still runs its tearDown(). If a tearDown() cleans up through the framework (a facade, $this->app), return early when zefram skipped the test, or it throws "A facade root has not been set":
protected function tearDown(): void { if ($this->zeframSkipped()) { parent::tearDown(); return; } Storage::disk('data')->delete('fixture.csv'); parent::tearDown(); }
The PHPStan extension (see below) flags an unguarded tearDown() like this.
Register the extension in phpunit.xml:
<extensions> <bootstrap class="Vusys\Zefram\PhpUnit\ZeframExtension"> <parameter name="enabled" value="true"/> <parameter name="cacheDirectory" value=".zefram"/> <parameter name="watchedPaths" value=".env,.env.testing,config/**,database/migrations/**,resources/views/**/*.blade.php"/> </bootstrap> </extensions>
Configure pcov to instrument your whole project (its default misses tests/):
pcov.enabled = 1 pcov.directory = /path/to/project pcov.exclude = "~/vendor/~"
Many PHP packages ship pcov with pcov.enabled = 0. Rather than editing php.ini, you can set it per run in a composer script:
"scripts": { "test": "@php -d pcov.enabled=1 -d pcov.directory=. -d pcov.exclude=\"~/vendor/~\" vendor/bin/phpunit" }
Add .zefram/ to .gitignore. Each PHPUnit configuration file gets its own directory inside it (.zefram/phpunit.xml-<hash>/), so suites run from separate configs, such as a browser suite, can share one cacheDirectory.
Laravel checklist
From trialling Zefram on real Laravel apps:
- Add
ZeframAwaretotests/TestCase.php. Laravel's ownTestCasedefinessetUp(), so if yours overrides it, call$this->zeframSetUp()first. - Guard any
tearDown()that uses a facade or$this->appwith$this->zeframSkipped()(see above). The PHPStan extension finds the unguarded ones. - Watch
.env,.env.testing,config/**,database/migrations/**, your Blade (or other template) sources, and any data files read at runtime. In the trial, an unwatched.envwas the only source of false skips. - Enable pcov for the run, with
pcov.directoryat the project root. - Browser tests that drive a served app (Tetryon, Dusk, Panther) run every time; see below. If they have their own PHPUnit config, it can share
.zefram/. - Tests extending plain
PHPUnit\Framework\TestCasewithout the trait always run. That's fine for fast unit tests.
Escape hatches
Coverage-as-critical-path is a heuristic. It cannot see env vars, time, randomness, network, or data read from files and databases at runtime. For tests with such dependencies:
#[\Vusys\Zefram\Attribute\NeverSkip]on a test class or method.neverSkipparameter with fnmatch patterns:<parameter name="neverSkip" value="App\Tests\Flaky\*"/>.watchedPathsfor file-shaped dependencies — any change to a matched file invalidates the entire cache. Patterns support**for recursive matching. Laravel users should always watchconfig/**(config files are visible to coverage only untilconfig:cachemakes them a blind spot — exactly the CI runs you want to accelerate) Blade sources (the compiled artifacts are deleted byview:clear), and.envplus.env.testing(dotenv is read withfile_get_contents, which coverage can't see; Laravel falls back to.envwhen.env.testingdoesn't exist). Also watch any data files the app reads at runtime, such as CSVs or JSON fixtures.ZEFRAM=0environment variable disables everything for a run.
Zefram also disables itself automatically when PHPUnit is collecting coverage (--coverage-*), since both would contend for pcov and skipped tests would falsify the report.
Browser tests against a served app
Browser tests that drive a separately served copy of the app aren't safe to skip. The controllers, middleware and views that answer the browser's requests run in the server process, which pcov in the test process never sees, so a change to them wouldn't invalidate the test. Zefram never skips a test extending a known base of this kind:
Vusys\Tetryon\PHPUnit\BrowserTestCaseandVusys\Tetryon\Laravel\BrowserTestCaseLaravel\Dusk\TestCaseSymfony\Component\Panther\PantherTestCase
For other out-of-process browser tests, add neverSkip for them
(<parameter name="neverSkip" value="Tests\Browser\*"/>), or leave the extension out of the
browser suite's PHPUnit config.
Finding NeverSkip candidates automatically
Rather than discovering a blind spot the hard way (a false skip in production), opt into
Vusys\Zefram\PHPStan\NeverSkipCandidateRule — a PHPStan rule that flags test methods
calling known non-deterministic/runtime-only things (rand(), time(), now(), an un-faked
Http:: call, raw curl_exec(), ...) without a #[NeverSkip] attribute already neutralizing
them. The same extension also loads Vusys\Zefram\PHPStan\UnguardedTearDownRule, which flags a
tearDown() that uses the framework before parent::tearDown() without checking
$this->zeframSkipped(). Add to your own phpstan.neon:
includes: - vendor/vusys/zefram/phpstan-extension.neon
Framework-agnostic checks always run; a handful of Laravel-aware checks (now(),
Carbon::now(), Http::, Auth::user(), env()) are name-matched the same way whether or
not Larastan is present in your project. It's a lint, not full dataflow analysis — a
preceding $this->travel(...)/freezeTime()/Carbon::setTestNow(...) (for time) or
Http::fake() (for HTTP) in the same method correctly neutralizes the calls after it, but it
doesn't know about your watchedPaths config — #[NeverSkip] is the only suppression it
understands.
CLI
vendor/bin/zefram clear
Deletes the entire cache directory (reads cacheDirectory from your
phpunit.xml's ZeframExtension parameter the same way the extension
itself does, defaulting to .zefram). Always clears everything — there's no
fingerprint-scoping argument, since stale fingerprint directories are
already pruned automatically during normal runs (any watched-path edit spins
up a fresh one, and the previous fingerprint's directory gets deleted the
next time you run your suite normally). A no-op, not an error, if the cache
directory doesn't exist yet.
vendor/bin/zefram stats vendor/bin/zefram stats --json
Reads .zefram/<config>/<fingerprint>/tests/*.json shards directly — no PHPUnit run
involved — and reports the total tracked tests, how many are eligible to
skip next run, and the aggregate stored duration (the sum of every test's
last recorded run time — roughly how much wall-clock a full run would
recover from skipping). The fingerprint is recomputed the same way a real
run would right now, so this always reflects your current composer.lock/
phpunit.xml/PHP version, not a stale cache from before your last dependency
bump. --json emits the same data as structured JSON, for CI scripting. It reports on phpunit.xml (or phpunit.xml.dist) only; other configs' records are kept but not counted.
Laravel
In a Laravel app, the same commands are also available as artisan commands — the package
service provider autodiscovers, no config/app.php edit needed:
php artisan zefram:clear php artisan zefram:stats --json
These are thin wrappers over the same classes the standalone CLI calls, so behavior can't
drift between the two entry points. Purely optional DX — the package itself has no runtime
illuminate/* dependency; Vusys\Zefram\Laravel\ZeframServiceProvider only ever loads inside
an app that already has Laravel installed.
Paratest
Zefram works under paratest's
default WrapperRunner, which distributes work per test class — exactly
what makes self-contained per-class shards (see How it works, above) safe
under parallelism: one worker owns one shard file per run, nothing to lock
or merge.
Every worker process only sees a partial slice of the suite, though, so a worker:
- Never prunes stale fingerprint directories or stale per-test records — pruning based on a partial view would delete state other workers still need.
- Never prints its own
Zefram: skipped ...summary line — with several concurrent workers each printing one, they'd interleave and mangle the terminal output.
Run vendor/bin/zefram stats (optionally --json for CI scripting) after
the full parallel run completes instead, to see the real aggregate numbers.
--functional mode is unsupported
Paratest's --functional mode distributes work per test method instead
of per class, which breaks the one-worker-owns-one-shard assumption above:
two methods of the same class can land on different worker processes, each
independently writing the same shard file (last writer wins).
There's no reliable way to detect --functional from inside a worker
process to guard against this — it's a flag paratest keeps entirely on its
own orchestrator side and never forwards to a worker (not in the
Configuration object extensions receive, not as an environment variable,
not anywhere else observable; see the docblock on
Vusys\Zefram\Paratest::isWorker() for the investigation). So this isn't
guarded against at runtime — it's simply unsupported. Worth noting for risk
assessment: because shards are self-contained and written atomically (see
How it works, above), the actual failure mode is a lost/overwritten
record, not a false skip — a clobbered test just reruns next time rather
than being incorrectly cached. Still, avoid --functional with Zefram
enabled.
CI
Without persisting .zefram/ across runs, every CI run starts cold and the
package never gets to skip anything there — which is one of the highest-value
places to see savings, since CI usually re-runs the same passing tests over
and over on unchanged code. actions/cache on GitHub Actions:
- name: Cache Zefram uses: actions/cache@v4 with: path: .zefram key: zefram-${{ runner.os }}-php${{ matrix.php }}-${{ hashFiles('composer.lock', 'phpunit.xml') }} restore-keys: | zefram-${{ runner.os }}-php${{ matrix.php }}- - name: Install dependencies run: composer install --no-interaction --prefer-dist - name: Test run: composer test
Place the cache step before composer install, keyed on the PHP version
you're building (matrix.php, or hardcode it outside a matrix) plus a hash
of composer.lock and phpunit.xml — the same two file-content inputs that
feed the global fingerprint (see How it works, above; PHP version and
package version round out the fingerprint but don't need to be hashed here
since they're already baked into the key or don't change within a job). The
restore-keys fallback means a partial match (e.g. after a composer.lock
bump changes the exact key) still restores whatever's on the cache instead
of starting fully cold — the fingerprint model already isolates the stale
entries the restored cache brings along into their own directory, so they're
harmless, just unused until pruned automatically on the next full run (see
the CLI section's clear command note above for how that pruning works).
If you run several PHPUnit configs (say, a browser suite in phpunit.browser.xml), add each to hashFiles(...); they share the cached .zefram/, one subdirectory per config.
Under paratest (see Paratest, above), the cache step doesn't need to change —
.zefram/ accumulates the same way regardless of how many workers wrote to
it, since each worker's shards are self-contained.
Development
composer install composer test # fast unit suite — run this on every save composer test:e2e # slower end-to-end suite: spawns real child PHPUnit processes # (dogfooding the package's own source, and a generated # dependency graph) — run before pushing, or in a dedicated CI job
composer test runs tests/Unit/; composer test:e2e runs tests/E2E/ (via a
separate <testsuite> in phpunit.xml, selected with --testsuite e2e). The
e2e suite needs pcov and skips itself
gracefully without it, same as the package.