Phpunit Tia Laravel Laravel Package

Getting Started

fruitcake/phpunit-tia-laravel wires PHPUnit's Test Impact Analysis into a Laravel app, so a test run only executes the tests that touch the files you changed. Instead of the whole suite on every save, you get a coverage-derived dependency map and a fast, targeted run.

1. Install into dev dependencies (it is a test-time tool, never a runtime one):

   composer require --dev fruitcake/phpunit-tia-laravel
   

   Check the resolved PHPUnit constraint — TIA is a recent PHPUnit feature, so the package will pin you to a version that supports it. If Composer wants to bump PHPUnit, do that deliberately in its own PR.

2. Register the extension in phpunit.xml inside the <extensions> block (the exact FQCN is in the package README — copy it verbatim rather than typing it):

   <extensions>
       <bootstrap class="Fruitcake\...\Extension"/>
   </extensions>
   

3. Make sure <source> is tight. TIA is only as good as the file list it tracks. Include app/ (and any first-party src/), exclude vendor/, and confirm bootstrap/cache and storage are not in scope. Over-broad source config is the number-one cause of "every test is affected".

4. First use case — build the map, then use it.

   • Cold run (one time, or on main): run the full suite with TIA recording enabled so the coverage-to-test graph is generated.
   • Warm run (day to day, on PRs): re-run with TIA enabled and only changed-file-adjacent tests execute. Persist the generated cache file between runs (CI artifact, or a local .phpunit.*cache file you keep out of git).

5. Where to look first when something is off: the README's config table, your phpunit.xml <source> block, and the TIA cache file itself. Deleting the cache and re-running the full suite fixes the majority of "weird selection" problems.

Implementation Patterns

Cold/warm is the core workflow. Every TIA setup has two modes and you must be explicit about which one CI is in. A common split:

Restore-then-run in CI. Cache the TIA artifact keyed on something stable (base branch + PHP version), restore it, run with TIA. On a cache miss, fall back to a full run rather than failing — TIA should degrade to "slow but correct", never to "fast but wrong".

Treat dependency-manifest changes as full-run triggers. If composer.lock, composer.json, phpunit.xml, or a service provider registration changed, skip TIA and run everything. These changes can alter behaviour in ways the coverage map cannot see.

Combine with --filter/--testsuite carefully. TIA narrows the candidate set; a --filter on top narrows it further. That's fine for local iteration, but don't let a stale filter mask a TIA selection bug during debugging — strip the filter first.

Parallel runs. If you use ParaTest, verify selection behaviour on the parallel runner before trusting it in CI — the extension runs per-process, and a partially restored cache across workers is a classic source of flaky "different tests ran this time" results. Run sequentially when validating.

Keep the local loop fast. Warm the cache locally once per branch (git checkout main && full run, then back to your branch) and the inner dev loop becomes seconds. This is where the package earns its keep day to day.

Bootstrap exclusion (v0.1.1). The release moves Laravel's application boot out of coverage collection. Practically: bootstrap/app.php, the framework kernel, and provider boot()/register() paths no longer get attributed to every single test. Before this, a warm cache reported nearly the entire suite as impacted on any change that touched boot code, which defeated the point. Upgrading is a pure win — expect noticeably smaller selected sets on warm runs.

Gotchas and Tips

• "No tests were selected" is a legitimate result — and a dangerous one. If you only changed config, Blade views, translations, or .env files, TIA may conclude nothing is affected and exit green having run zero tests. Gate on this: if the diff touches non-PHP assets, force a full run. Blade templates in particular are compiled and cached, so changes often aren't visible to a PHP coverage map.

• Coverage driver required. TIA needs Xdebug or PCOV to build the map. The recording run is meaningfully slower than a normal run — don't be alarmed, and don't run it on every keystroke. Use PCOV in CI if you can; Xdebug's overhead is significant.

• Cache invalidation is the debugging skill. Symptom: a warm run misses a test you know should fail. Fix: delete the TIA cache, run the full suite, reproduce the failure, then re-check warm behaviour. If the failure reappears only after a cold run, your <source> include list is wrong, not the extension.

• v0.1.1 changes what warm caches contain, so the first run after upgrading should be a cold/full run. Reusing a cache generated by 0.1.0 will carry the old bootstrap-attributed entries until it's rebuilt.

• Bootstrap changes are now under-detected. The flip side of the 0.1.1 fix: if you edit bootstrap/app.php, middleware registration, or provider wiring, the coverage map no longer flags those files. Add an explicit rule — "diff touches bootstrap/, config/, or app/Providers/ → full suite".

• Don't commit the cache. Add the TIA cache file to .gitignore. It's machine- and run-specific, and a stale committed cache is worse than no cache.

• Watch CI artifact size and TTL. The cache grows with suite size; set an expiry and don't let it accumulate per-commit keys — key on the base branch, not on the SHA, or you'll never get a cache hit.

• Verify selection, don't trust it. Periodically diff the warm run's executed test count against the full suite on the same commit. A gradual drift downward is the signature of a source-config regression, and it's silent.

• Extension points. The config exposes ignore/exclude paths; use them to keep generated code, DTOs, or heavily-mocked infrastructure out of the map rather than letting false positives bloat every run. Reach for config before patching the extension.