README

PHPUnit TIA

This is a port of Pest's new TIA Engine. Test Impact Analysis (TIA) greatly improves test suite performance by only running tests which relate to impacted (changed) files. This extension brings the same performance improvements to PHPUnit.

Installation

This extension requires PHPUnit 13 and PHP 8.4, as well as a code coverage driver (pcov or Xdebug in coverage mode) to record new coverage. If you are not running PHPUnit 13, you may use Shift to automate the upgrade.

Note: TIA automatically tracks which files each test exercises, but for large suites, we recommend php-code-coverage 14.3+ for lower memory use during coverage collection.

composer require --dev jasonmccreary/phpunit-tia

Next, register the extension in your PHPUnit configuration:

<extensions>
    <bootstrap class="JMac\Testing\PhpUnit\Tia\Extension">
        <parameter name="storage" value="global"/>
    </bootstrap>
</extensions>

When the current branch has no baseline of its own, TIA falls back to main by default. To use another branch, add the fallback-branch parameter:

<parameter name="fallback-branch" value="develop"/>

The fallback branch is used only for reading cached results, the recorded commit, and the last-run tree. New results are still recorded under the current branch.

Usage

To enable TIA, add the trait to your base TestCase:

use JMac\Testing\PhpUnit\Tia\Traits\RunWithTia;

abstract class TestCase extends \PHPUnit\Framework\TestCase
{
    use RunWithTia;
}

This will activate TIA for every phpunit invocation. Since third-party extensions can not change the PHPUnit test runner, TIA marks unimpacted tests as skipped (S) to achieve faster replay speeds.

Note: if your TestCase already declares setUp(), you will need to alias and call the trait's setUp explicitly:

abstract class TestCase extends \PHPUnit\Framework\TestCase
{
    use RunWithTia {
        RunWithTia::setUp as tiaSetUp;
    }

    protected function setUp(): void
    {
        $this->tiaSetUp();

        // ...your own setUp logic
    }
}

To bypass TIA, you may pass an environment variable at runtime:

PHPUNIT_TIA=0 phpunit ...

While a baseline will be established automatically, you may pass an environment variable to rebuild:

PHPUNIT_TIA_FRESH=1 phpunit ...

Note: running tests with the --fail-on-skipped or --display-skipped option will automatically bypass TIA's speed boost. You will need to drop these options to take full advantage of TIA.

Debugging a test that won't skip

If a test keeps running when you expect TIA to skip it, pass an environment variable to have TIA explain why on STDERR, one line per test that actually ran:

PHPUNIT_TIA_DEBUG=1 phpunit ...

TIA-DEBUG: running Tests\FooTest::test_it_works — source changed: src/Foo.php

A common cause: TIA's change detection includes git status, so any file a test run writes back into the project tree (a fixture database, a generated upload, a cache directory) looks "changed" on every run if it isn't .gitignored — and can mark every test that shares its directory as affected. If the reported reason names a file you didn't intentionally edit, .gitignore it and re-run.

CI Workflows

To use TIA in CI, your baseline graph must persist between runs. See our own GitHub Action workflow for an example. At a high level, your workflow needs to:

Check out with full git history (fetch-depth: 0), since TIA diffs against a baseline commit
Re-attach HEAD to the real branch name, since a detached HEAD collapses baselines across branches
Cache TIA's storage directory (~/.phpunit-tia for global storage, or the configured path for local) keyed per-branch/runner, and save it after every run

Note: TIA is intended to reduce the feedback loop during development. As such, an ideal workflow is using TIA in local environments and running the full test suite in CI environments.

Contributing

You may contribute by opening a Pull Request with your changes. All PRs should target main, include tests to verify your change, and pass the GitHub Action workflows.

jasonmccreary / phpunit-tia

Package info

Security

Statistics