style

[4.x] Time based sharding

.github/workflows/static.yml

@@ -11,6 +11,9 @@ concurrency:
   group: static-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   static:
     if: github.event_name != 'schedule' || github.repository == 'pestphp/pest'
@@ -44,7 +47,7 @@ jobs:
       uses: actions/cache@v5
       with:
         path: ${{ steps.composer-cache.outputs.dir }}
-        key: static-php-8.3-${{ matrix.dependency-version }}-composer-${{ hashFiles('**/composer.json') }}
+        key: static-php-8.3-${{ matrix.dependency-version }}-composer-${{ hashFiles('**/composer.json', '**/composer.lock') }}
         restore-keys: |
           static-php-8.3-${{ matrix.dependency-version }}-composer-
           static-php-8.3-composer-

.github/workflows/tests.yml

@@ -11,6 +11,9 @@ concurrency:
   group: tests-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
   tests:
     if: github.event_name != 'schedule' || github.repository == 'pestphp/pest'
@@ -51,7 +54,7 @@ jobs:
       uses: actions/cache@v5
       with:
         path: ${{ steps.composer-cache.outputs.dir }}
-        key: ${{ matrix.os }}-php-${{ matrix.php }}-symfony-${{ matrix.symfony }}-composer-${{ hashFiles('**/composer.json') }}
+        key: ${{ matrix.os }}-php-${{ matrix.php }}-symfony-${{ matrix.symfony }}-composer-${{ hashFiles('**/composer.json', '**/composer.lock') }}
         restore-keys: |
           ${{ matrix.os }}-php-${{ matrix.php }}-symfony-${{ matrix.symfony }}-composer-
           ${{ matrix.os }}-php-${{ matrix.php }}-composer-

composer.json

@@ -19,18 +19,18 @@
     "require": {
         "php": "^8.3.0",
         "brianium/paratest": "^7.20.0",
-        "nunomaduro/collision": "^8.9.3",
+        "nunomaduro/collision": "^8.9.4",
         "nunomaduro/termwind": "^2.4.0",
         "pestphp/pest-plugin": "^4.0.0",
         "pestphp/pest-plugin-arch": "^4.0.2",
         "pestphp/pest-plugin-mutate": "^4.0.1",
         "pestphp/pest-plugin-profanity": "^4.2.1",
-        "phpunit/phpunit": "^12.5.16",
+        "phpunit/phpunit": "^12.5.23",
         "symfony/process": "^7.4.8|^8.0.8"
     },
     "conflict": {
         "filp/whoops": "<2.18.3",
-        "phpunit/phpunit": ">12.5.16",
+        "phpunit/phpunit": ">12.5.23",
         "sebastian/exporter": "<7.0.0",
         "webmozart/assert": "<1.11.0"
     },
@@ -123,6 +123,7 @@
                 "Pest\\Plugins\\Verbose",
                 "Pest\\Plugins\\Version",
                 "Pest\\Plugins\\Shard",
+                "Pest\\Plugins\\Tia",
                 "Pest\\Plugins\\Parallel"
             ]
         },

overrides/Logging/JUnit/JunitXmlLogger.php

@@ -1,6 +1,39 @@
 <?php
 
+/*
+ * BSD 3-Clause License
+ *
+ * Copyright (c) 2001-2023, Sebastian Bergmann
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ *    list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
 declare(strict_types=1);
+
 /*
  * This file is part of PHPUnit.
  *

overrides/Runner/TestSuiteSorter.php

@@ -0,0 +1,388 @@
+<?php
+
+/*
+ * BSD 3-Clause License
+ *
+ * Copyright (c) 2001-2023, Sebastian Bergmann
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice, this
+ *    list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace PHPUnit\Runner;
+
+use PHPUnit\Framework\DataProviderTestSuite;
+use PHPUnit\Framework\Reorderable;
+use PHPUnit\Framework\Test;
+use PHPUnit\Framework\TestCase;
+use PHPUnit\Framework\TestSuite;
+use PHPUnit\Runner\ResultCache\NullResultCache;
+use PHPUnit\Runner\ResultCache\ResultCache;
+use PHPUnit\Runner\ResultCache\ResultCacheId;
+
+use function array_diff;
+use function array_merge;
+use function array_reverse;
+use function array_splice;
+use function assert;
+use function count;
+use function in_array;
+use function max;
+use function shuffle;
+use function usort;
+
+/**
+ * @internal This class is not covered by the backward compatibility promise for PHPUnit
+ */
+final class TestSuiteSorter
+{
+    public const int ORDER_DEFAULT = 0;
+
+    public const int ORDER_RANDOMIZED = 1;
+
+    public const int ORDER_REVERSED = 2;
+
+    public const int ORDER_DEFECTS_FIRST = 3;
+
+    public const int ORDER_DURATION = 4;
+
+    public const int ORDER_SIZE = 5;
+
+    /**
+     * @var non-empty-array<non-empty-string, positive-int>
+     */
+    private const array SIZE_SORT_WEIGHT = [
+        'small' => 1,
+        'medium' => 2,
+        'large' => 3,
+        'unknown' => 4,
+    ];
+
+    /**
+     * @var array<string, int> Associative array of (string => DEFECT_SORT_WEIGHT) elements
+     */
+    private array $defectSortOrder = [];
+
+    private readonly ResultCache $cache;
+
+    public function __construct(?ResultCache $cache = null)
+    {
+        $this->cache = $cache ?? new NullResultCache;
+    }
+
+    /**
+     * @throws Exception
+     */
+    public function reorderTestsInSuite(Test $suite, int $order, bool $resolveDependencies, int $orderDefects): void
+    {
+        $allowedOrders = [
+            self::ORDER_DEFAULT,
+            self::ORDER_REVERSED,
+            self::ORDER_RANDOMIZED,
+            self::ORDER_DURATION,
+            self::ORDER_SIZE,
+        ];
+
+        if (! in_array($order, $allowedOrders, true)) {
+            // @codeCoverageIgnoreStart
+            throw new InvalidOrderException;
+            // @codeCoverageIgnoreEnd
+        }
+
+        $allowedOrderDefects = [
+            self::ORDER_DEFAULT,
+            self::ORDER_DEFECTS_FIRST,
+        ];
+
+        if (! in_array($orderDefects, $allowedOrderDefects, true)) {
+            // @codeCoverageIgnoreStart
+            throw new InvalidOrderException;
+            // @codeCoverageIgnoreEnd
+        }
+
+        if ($suite instanceof TestSuite) {
+            foreach ($suite as $_suite) {
+                $this->reorderTestsInSuite($_suite, $order, $resolveDependencies, $orderDefects);
+            }
+
+            if ($orderDefects === self::ORDER_DEFECTS_FIRST) {
+                $this->addSuiteToDefectSortOrder($suite);
+            }
+
+            $this->sort($suite, $order, $resolveDependencies, $orderDefects);
+        }
+    }
+
+    private function sort(TestSuite $suite, int $order, bool $resolveDependencies, int $orderDefects): void
+    {
+        if ($suite->tests() === []) {
+            return;
+        }
+
+        if ($order === self::ORDER_REVERSED) {
+            $suite->setTests($this->reverse($suite->tests()));
+        } elseif ($order === self::ORDER_RANDOMIZED) {
+            $suite->setTests($this->randomize($suite->tests()));
+        } elseif ($order === self::ORDER_DURATION) {
+            $suite->setTests($this->sortByDuration($suite->tests()));
+        } elseif ($order === self::ORDER_SIZE) {
+            $suite->setTests($this->sortBySize($suite->tests()));
+        }
+
+        if ($orderDefects === self::ORDER_DEFECTS_FIRST) {
+            $suite->setTests($this->sortDefectsFirst($suite->tests()));
+        }
+
+        if ($resolveDependencies && ! ($suite instanceof DataProviderTestSuite)) {
+            $tests = $suite->tests();
+
+            /** @noinspection PhpParamsInspection */
+            /** @phpstan-ignore argument.type */
+            $suite->setTests($this->resolveDependencies($tests));
+        }
+    }
+
+    private function addSuiteToDefectSortOrder(TestSuite $suite): void
+    {
+        $max = 0;
+
+        foreach ($suite->tests() as $test) {
+            assert($test instanceof Reorderable);
+
+            $sortId = $test->sortId();
+
+            if (! isset($this->defectSortOrder[$sortId])) {
+                $this->defectSortOrder[$sortId] = $this->cache->status(ResultCacheId::fromReorderable($test))->asInt();
+                $max = max($max, $this->defectSortOrder[$sortId]);
+            }
+        }
+
+        $this->defectSortOrder[$suite->sortId()] = $max;
+    }
+
+    /**
+     * @param  list<Test>  $tests
+     * @return list<Test>
+     */
+    private function reverse(array $tests): array
+    {
+        return array_reverse($tests);
+    }
+
+    /**
+     * @param  list<Test>  $tests
+     * @return list<Test>
+     */
+    private function randomize(array $tests): array
+    {
+        shuffle($tests);
+
+        return $tests;
+    }
+
+    /**
+     * @param  list<Test>  $tests
+     * @return list<Test>
+     */
+    private function sortDefectsFirst(array $tests): array
+    {
+        usort(
+            $tests,
+            fn (Test $left, Test $right) => $this->cmpDefectPriorityAndTime($left, $right),
+        );
+
+        return $tests;
+    }
+
+    /**
+     * @param  list<Test>  $tests
+     * @return list<Test>
+     */
+    private function sortByDuration(array $tests): array
+    {
+        usort(
+            $tests,
+            fn (Test $left, Test $right) => $this->cmpDuration($left, $right),
+        );
+
+        return $tests;
+    }
+
+    /**
+     * @param  list<Test>  $tests
+     * @return list<Test>
+     */
+    private function sortBySize(array $tests): array
+    {
+        usort(
+            $tests,
+            fn (Test $left, Test $right) => $this->cmpSize($left, $right),
+        );
+
+        return $tests;
+    }
+
+    /**
+     * Comparator callback function to sort tests for "reach failure as fast as possible".
+     *
+     * 1. sort tests by defect weight defined in self::DEFECT_SORT_WEIGHT
+     * 2. when tests are equally defective, sort the fastest to the front
+     * 3. do not reorder successful tests
+     */
+    private function cmpDefectPriorityAndTime(Test $a, Test $b): int
+    {
+        assert($a instanceof Reorderable);
+        assert($b instanceof Reorderable);
+
+        $priorityA = $this->defectSortOrder[$a->sortId()] ?? 0;
+        $priorityB = $this->defectSortOrder[$b->sortId()] ?? 0;
+
+        if ($priorityA !== $priorityB) {
+            // Sort defect weight descending
+            return $priorityB <=> $priorityA;
+        }
+
+        if ($priorityA > 0 || $priorityB > 0) {
+            return $this->cmpDuration($a, $b);
+        }
+
+        // do not change execution order
+        return 0;
+    }
+
+    /**
+     * Compares test duration for sorting tests by duration ascending.
+     */
+    private function cmpDuration(Test $a, Test $b): int
+    {
+        if (! ($a instanceof Reorderable && $b instanceof Reorderable)) {
+            return 0;
+        }
+
+        return $this->cache->time(ResultCacheId::fromReorderable($a)) <=> $this->cache->time(ResultCacheId::fromReorderable($b));
+    }
+
+    /**
+     * Compares test size for sorting tests small->medium->large->unknown.
+     */
+    private function cmpSize(Test $a, Test $b): int
+    {
+        $sizeA = ($a instanceof TestCase || $a instanceof DataProviderTestSuite)
+            ? $a->size()->asString()
+            : 'unknown';
+        $sizeB = ($b instanceof TestCase || $b instanceof DataProviderTestSuite)
+            ? $b->size()->asString()
+            : 'unknown';
+
+        return self::SIZE_SORT_WEIGHT[$sizeA] <=> self::SIZE_SORT_WEIGHT[$sizeB];
+    }
+
+    /**
+     * Reorder Tests within a TestCase in such a way as to resolve as many dependencies as possible.
+     * The algorithm will leave the tests in original running order when it can.
+     * For more details see the documentation for test dependencies.
+     *
+     * Short description of algorithm:
+     * 1. Pick the next Test from remaining tests to be checked for dependencies.
+     * 2. If the test has no dependencies: mark done, start again from the top
+     * 3. If the test has dependencies but none left to do: mark done, start again from the top
+     * 4. When we reach the end add any leftover tests to the end. These will be marked 'skipped' during execution.
+     *
+     * @param  array<TestCase>  $tests
+     * @return array<TestCase>
+     */
+    private function resolveDependencies(array $tests): array
+    {
+        // Pest: Fast-path. If no test in this suite declares dependencies, the
+        // original O(N^2) algorithm is wasted work — it would splice each test
+        // one-by-one back into the same order. The check deliberately walks
+        // TestCase instances directly instead of calling TestSuite::requires(),
+        // because the latter lazily builds TestSuite::provides() via
+        // ExecutionOrderDependency::mergeUnique, which is O(N^2) in the total
+        // number of tests. With thousands of tests that single call alone can
+        // burn several seconds before the sort even begins. Reading the
+        // cached TestCase::$dependencies property stays O(N) and costs nothing
+        // when no test uses `->depends()` / PHPUnit `@depends`.
+        if (! $this->anyTestHasDependencies($tests)) {
+            return $tests;
+        }
+
+        $newTestOrder = [];
+        $i = 0;
+        $provided = [];
+
+        do {
+            if (array_diff($tests[$i]->requires(), $provided) === []) {
+                $provided = array_merge($provided, $tests[$i]->provides());
+                $newTestOrder = array_merge($newTestOrder, array_splice($tests, $i, 1));
+                $i = 0;
+            } else {
+                $i++;
+            }
+        } while ($tests !== [] && ($i < count($tests)));
+
+        return array_merge($newTestOrder, $tests);
+    }
+
+    /**
+     * Cheaply determines whether any test in the tree declares @depends.
+     *
+     * Walks `TestSuite` containers recursively and inspects each `TestCase`
+     * directly so it never triggers `TestSuite::provides()`, which is O(N^2)
+     * in the total number of aggregated tests.
+     *
+     * @param  iterable<Test>  $tests
+     */
+    private function anyTestHasDependencies(iterable $tests): bool
+    {
+        foreach ($tests as $test) {
+            if ($test instanceof TestSuite) {
+                if ($this->anyTestHasDependencies($test->tests())) {
+                    return true;
+                }
+
+                continue;
+            }
+
+            if ($test instanceof TestCase && $test->requires() !== []) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}

src/ArchPresets/Laravel.php

@@ -176,9 +176,5 @@ final class Laravel extends AbstractPreset
             ->toImplement('Illuminate\Contracts\Container\ContextualAttribute')
             ->toHaveAttribute('Attribute')
             ->toHaveMethod('resolve');
-
-        $this->expectations[] = expect('App\Rules')
-            ->classes()
-            ->toImplement('Illuminate\Contracts\Validation\ValidationRule');
     }
 }

src/Bootstrappers/BootOverrides.php

@@ -21,6 +21,7 @@ final class BootOverrides implements Bootstrapper
         'Runner/Filter/NameFilterIterator.php',
         'Runner/ResultCache/DefaultResultCache.php',
         'Runner/TestSuiteLoader.php',
+        'Runner/TestSuiteSorter.php',
         'TextUI/Command/Commands/WarmCodeCoverageCacheCommand.php',
         'TextUI/Output/Default/ProgressPrinter/Subscriber/TestSkippedSubscriber.php',
         'TextUI/TestSuiteFilterProcessor.php',

src/Bootstrappers/BootSubscribers.php

@@ -25,6 +25,16 @@ final readonly class BootSubscribers implements Bootstrapper
         Subscribers\EnsureIgnorableTestCasesAreIgnored::class,
         Subscribers\EnsureKernelDumpIsFlushed::class,
         Subscribers\EnsureTeamCityEnabled::class,
+        Subscribers\EnsureTiaCoverageIsRecorded::class,
+        Subscribers\EnsureTiaCoverageIsFlushed::class,
+        Subscribers\EnsureTiaResultsAreCollected::class,
+        Subscribers\EnsureTiaResultIsRecordedOnPassed::class,
+        Subscribers\EnsureTiaResultIsRecordedOnFailed::class,
+        Subscribers\EnsureTiaResultIsRecordedOnErrored::class,
+        Subscribers\EnsureTiaResultIsRecordedOnSkipped::class,
+        Subscribers\EnsureTiaResultIsRecordedOnIncomplete::class,
+        Subscribers\EnsureTiaResultIsRecordedOnRisky::class,
+        Subscribers\EnsureTiaAssertionsAreRecordedOnFinished::class,
     ];
 
     /**

src/Concerns/Testable.php

@@ -7,12 +7,15 @@ namespace Pest\Concerns;
 use Closure;
 use Pest\Exceptions\DatasetArgumentsMismatch;
 use Pest\Panic;
+use Pest\Plugins\Tia;
 use Pest\Preset;
 use Pest\Support\ChainableClosure;
+use Pest\Support\Container;
 use Pest\Support\ExceptionTrace;
 use Pest\Support\Reflection;
 use Pest\Support\Shell;
 use Pest\TestSuite;
+use PHPUnit\Framework\AssertionFailedError;
 use PHPUnit\Framework\Attributes\PostCondition;
 use PHPUnit\Framework\IncompleteTest;
 use PHPUnit\Framework\SkippedTest;
@@ -75,6 +78,12 @@ trait Testable
      */
     public bool $__ran = false;
 
+    /**
+     * Set when a `BeforeEachable` plugin returns a cached success result.
+     * Checked in `__runTest` and `tearDown` to skip body + cleanup.
+     */
+    private bool $__cachedPass = false;
+
     /**
      * The test's test closure.
      */
@@ -227,6 +236,45 @@ trait Testable
     {
         TestSuite::getInstance()->test = $this;
 
+        $this->__cachedPass = false;
+
+        /** @var Tia $tia */
+        $tia = Container::getInstance()->get(Tia::class);
+        $cached = $tia->getCachedResult(self::$__filename, $this::class.'::'.$this->name());
+
+        if ($cached !== null) {
+            if ($cached->isSuccess()) {
+                $this->__cachedPass = true;
+
+                return;
+            }
+
+            // Risky tests have no public PHPUnit hook to replay as-risky.
+            // Best available: short-circuit as a pass so the test doesn't
+            // misreport as a failure. Aggregate risky totals won't
+            // survive replay — accepted trade-off until PHPUnit grows a
+            // programmatic risky-marker API.
+            if ($cached->isRisky()) {
+                $this->__cachedPass = true;
+
+                return;
+            }
+
+            // Non-success: throw the matching PHPUnit exception. Runner
+            // catches it and marks the test with the correct status so
+            // skips, failures, incompletes and todos appear in output
+            // exactly as they did in the cached run.
+            if ($cached->isSkipped()) {
+                $this->markTestSkipped($cached->message());
+            }
+
+            if ($cached->isIncomplete()) {
+                $this->markTestIncomplete($cached->message());
+            }
+
+            throw new AssertionFailedError($cached->message() ?: 'Cached failure');
+        }
+
         $method = TestSuite::getInstance()->tests->get(self::$__filename)->getMethod($this->name());
 
         $description = $method->description;
@@ -302,6 +350,12 @@ trait Testable
      */
     protected function tearDown(...$arguments): void
     {
+        if ($this->__cachedPass) {
+            TestSuite::getInstance()->test = null;
+
+            return;
+        }
+
         $afterEach = TestSuite::getInstance()->afterEach->get(self::$__filename);
 
         if ($this->__afterEach instanceof Closure) {
@@ -327,6 +381,19 @@ trait Testable
      */
     private function __runTest(Closure $closure, ...$args): mixed
     {
+        if ($this->__cachedPass) {
+            // Feed the exact assertion count captured during the recorded
+            // run so Pest's "Tests: N passed (M assertions)" banner stays
+            // accurate on replay instead of collapsing to 1-per-test.
+            /** @var Tia $tia */
+            $tia = Container::getInstance()->get(Tia::class);
+            $assertions = $tia->getCachedAssertions($this::class.'::'.$this->name());
+
+            $this->addToAssertionCount($assertions > 0 ? $assertions : 1);
+
+            return null;
+        }
+
         $arguments = $this->__resolveTestArguments($args);
         $this->__ensureDatasetArgumentNameAndNumberMatches($arguments);
 

src/Configuration.php

@@ -119,6 +119,14 @@ final readonly class Configuration
         return new Browser\Configuration;
     }
 
+    /**
+     * Gets the TIA (Test Impact Analysis) configuration.
+     */
+    public function tia(): Plugins\Tia\Configuration
+    {
+        return new Plugins\Tia\Configuration;
+    }
+
     /**
      * Proxies calls to the uses method.
      *

src/Kernel.php

@@ -36,6 +36,7 @@ final readonly class Kernel
      */
     private const array BOOTSTRAPPERS = [
         Bootstrappers\BootOverrides::class,
+        Plugins\Tia\Bootstrapper::class,
         Bootstrappers\BootSubscribers::class,
         Bootstrappers\BootFiles::class,
         Bootstrappers\BootView::class,

src/Mixins/Expectation.php

@@ -14,6 +14,7 @@ use InvalidArgumentException;
 use JsonSerializable;
 use Pest\Exceptions\InvalidExpectationValue;
 use Pest\Matchers\Any;
+use Pest\Plugins\Snapshot;
 use Pest\Support\Arr;
 use Pest\Support\Exporter;
 use Pest\Support\NullClosure;
@@ -851,18 +852,31 @@ final class Expectation
             default => InvalidExpectationValue::expected('array|object|string'),
         };
 
-        if ($snapshots->has()) {
+        if (! $snapshots->has()) {
-            [$filename, $content] = $snapshots->get();
-
-            Assert::assertSame(
-                strtr($content, ["\r\n" => "\n", "\r" => "\n"]),
-                strtr($string, ["\r\n" => "\n", "\r" => "\n"]),
-                $message === '' ? "Failed asserting that the string value matches its snapshot ($filename)." : $message
-            );
-        } else {
             $filename = $snapshots->save($string);
 
             TestSuite::getInstance()->registerSnapshotChange("Snapshot created at [$filename]");
+        } else {
+            [$filename, $content] = $snapshots->get();
+
+            $normalizedContent = strtr($content, ["\r\n" => "\n", "\r" => "\n"]);
+            $normalizedString = strtr($string, ["\r\n" => "\n", "\r" => "\n"]);
+
+            if (Snapshot::$updateSnapshots && $normalizedContent !== $normalizedString) {
+                $snapshots->save($string);
+
+                TestSuite::getInstance()->registerSnapshotChange("Snapshot updated at [$filename]");
+            } else {
+                if (Snapshot::$updateSnapshots) {
+                    TestSuite::getInstance()->registerSnapshotChange("Snapshot unchanged at [$filename]");
+                }
+
+                Assert::assertSame(
+                    $normalizedContent,
+                    $normalizedString,
+                    $message === '' ? "Failed asserting that the string value matches its snapshot ($filename)." : $message
+                );
+            }
         }
 
         return $this;

src/Pest.php

@@ -6,7 +6,7 @@ namespace Pest;
 
 function version(): string
 {
-    return '4.4.4';
+    return '4.6.3';
 }
 
 function testDirectory(string $file = ''): string

src/Plugins/Help.php

@@ -123,6 +123,10 @@ final readonly class Help implements HandlesArguments
                 'arg' => '--update-snapshots',
                 'desc' => 'Update snapshots for tests using the "toMatchSnapshot" expectation',
             ],
+            [
+                'arg' => '--update-shards',
+                'desc' => 'Update shards.json with test timing data for time-balanced sharding',
+            ],
         ], ...$content['Execution']];
 
         $content['Selection'] = [[

src/Plugins/Shard.php

@@ -6,7 +6,13 @@ namespace Pest\Plugins;
 
 use Pest\Contracts\Plugins\AddsOutput;
 use Pest\Contracts\Plugins\HandlesArguments;
+use Pest\Contracts\Plugins\Terminable;
 use Pest\Exceptions\InvalidOption;
+use Pest\Subscribers\EnsureShardTimingFinished;
+use Pest\Subscribers\EnsureShardTimingsAreCollected;
+use Pest\Subscribers\EnsureShardTimingStarted;
+use Pest\TestSuite;
+use PHPUnit\Event;
 use Symfony\Component\Console\Input\ArgvInput;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
@@ -15,7 +21,7 @@ use Symfony\Component\Process\Process;
 /**
  * @internal
  */
-final class Shard implements AddsOutput, HandlesArguments
+final class Shard implements AddsOutput, HandlesArguments, Terminable
 {
     use Concerns\HandleArguments;
 
@@ -33,6 +39,40 @@ final class Shard implements AddsOutput, HandlesArguments
      */
     private static ?array $shard = null;
 
+    /**
+     * Whether to update the shards.json file.
+     */
+    private static bool $updateShards = false;
+
+    /**
+     * Whether time-balanced sharding was used.
+     */
+    private static bool $timeBalanced = false;
+
+    /**
+     * Whether the shards.json file is outdated.
+     */
+    private static bool $shardsOutdated = false;
+
+    /**
+     * Whether the test suite passed.
+     */
+    private static bool $passed = false;
+
+    /**
+     * Collected timings from workers or subscribers.
+     *
+     * @var array<string, float>|null
+     */
+    private static ?array $collectedTimings = null;
+
+    /**
+     * The canonical list of test classes from --list-tests.
+     *
+     * @var list<string>|null
+     */
+    private static ?array $knownTests = null;
+
     /**
      * Creates a new Plugin instance.
      */
@@ -47,6 +87,19 @@ final class Shard implements AddsOutput, HandlesArguments
      */
     public function handleArguments(array $arguments): array
     {
+        if ($this->hasArgument('--update-shards', $arguments)) {
+            return $this->handleUpdateShards($arguments);
+        }
+
+        if (Parallel::isWorker() && Parallel::getGlobal('UPDATE_SHARDS') === true) {
+            self::$updateShards = true;
+
+            Event\Facade::instance()->registerSubscriber(new EnsureShardTimingStarted);
+            Event\Facade::instance()->registerSubscriber(new EnsureShardTimingFinished);
+
+            return $arguments;
+        }
+
         if (! $this->hasArgument('--shard', $arguments)) {
             return $arguments;
         }
@@ -63,7 +116,24 @@ final class Shard implements AddsOutput, HandlesArguments
 
         /** @phpstan-ignore-next-line */
         $tests = $this->allTests($arguments);
+
+        $timings = $this->loadShardsFile();
+        if ($timings !== null) {
+            $knownTests = array_values(array_filter($tests, fn (string $test): bool => isset($timings[$test])));
+            $newTests = array_values(array_diff($tests, $knownTests));
+
+            $partitions = $this->partitionByTime($knownTests, $timings, $total);
+
+            foreach ($newTests as $i => $test) {
+                $partitions[$i % $total][] = $test;
+            }
+
+            $testsToRun = $partitions[$index - 1] ?? [];
+            self::$timeBalanced = true;
+            self::$shardsOutdated = $newTests !== [];
+        } else {
             $testsToRun = (array_chunk($tests, max(1, (int) ceil(count($tests) / $total))))[$index - 1] ?? [];
+        }
 
         self::$shard = [
             'index' => $index,
@@ -72,9 +142,43 @@ final class Shard implements AddsOutput, HandlesArguments
             'testsCount' => count($tests),
         ];
 
+        if ($testsToRun === []) {
+            return $arguments;
+        }
+
         return [...$arguments, '--filter', $this->buildFilterArgument($testsToRun)];
     }
 
+    /**
+     * Handles the --update-shards argument.
+     *
+     * @param  array<int, string>  $arguments
+     * @return array<int, string>
+     */
+    private function handleUpdateShards(array $arguments): array
+    {
+        if ($this->hasArgument('--shard', $arguments)) {
+            throw new InvalidOption('The [--update-shards] option cannot be combined with [--shard].');
+        }
+
+        $arguments = $this->popArgument('--update-shards', $arguments);
+
+        self::$updateShards = true;
+
+        /** @phpstan-ignore-next-line */
+        self::$knownTests = $this->allTests($arguments);
+
+        if ($this->hasArgument('--parallel', $arguments) || $this->hasArgument('-p', $arguments)) {
+            Parallel::setGlobal('UPDATE_SHARDS', true);
+            Parallel::setGlobal('SHARD_RUN_ID', uniqid('pest-shard-', true));
+        } else {
+            Event\Facade::instance()->registerSubscriber(new EnsureShardTimingStarted);
+            Event\Facade::instance()->registerSubscriber(new EnsureShardTimingFinished);
+        }
+
+        return $arguments;
+    }
+
     /**
      * Returns all tests that the test suite would run.
      *
@@ -87,7 +191,7 @@ final class Shard implements AddsOutput, HandlesArguments
             'php',
             ...$this->removeParallelArguments($arguments),
             '--list-tests',
-        ]))->mustRun()->getOutput();
+        ]))->setTimeout(120)->mustRun()->getOutput();
 
         preg_match_all('/ - (?:P\\\\)?(Tests\\\\[^:]+)::/', $output, $matches);
 
@@ -116,6 +220,22 @@ final class Shard implements AddsOutput, HandlesArguments
      */
     public function addOutput(int $exitCode): int
     {
+        self::$passed = $exitCode === 0;
+
+        if (self::$updateShards && self::$passed && ! Parallel::isWorker()) {
+            self::$collectedTimings = $this->collectTimings();
+
+            $count = self::$knownTests !== null
+                ? count(array_intersect_key(self::$collectedTimings, array_flip(self::$knownTests)))
+                : count(self::$collectedTimings);
+
+            $this->output->writeln(sprintf(
+                '  <fg=gray>Shards:</>   <fg=default>shards.json updated with timings for %d test class%s.</>',
+                $count,
+                $count === 1 ? '' : 'es',
+            ));
+        }
+
         if (self::$shard === null) {
             return $exitCode;
         }
@@ -128,17 +248,250 @@ final class Shard implements AddsOutput, HandlesArguments
         ] = self::$shard;
 
         $this->output->writeln(sprintf(
-            '  <fg=gray>Shard:</>    <fg=default>%d of %d</> — %d file%s ran, out of %d.',
+            '  <fg=gray>Shard:</>    <fg=default>%d of %d</> — %d file%s ran, out of %d%s.',
             $index,
             $total,
             $testsRan,
             $testsRan === 1 ? '' : 's',
             $testsCount,
+            self::$timeBalanced ? ' <fg=gray>(time-balanced)</>' : '',
         ));
 
+        if (self::$shardsOutdated) {
+            $this->output->writeln('  <fg=yellow;options=bold>WARN</>  <fg=default>The [tests/.pest/shards.json] file is out of date. Run [--update-shards] to update it.</>');
+        }
+
         return $exitCode;
     }
 
+    /**
+     * Terminates the plugin.
+     */
+    public function terminate(): void
+    {
+        if (! self::$updateShards) {
+            return;
+        }
+
+        if (Parallel::isWorker()) {
+            $this->writeWorkerTimings();
+
+            return;
+        }
+
+        if (! self::$passed) {
+            return;
+        }
+
+        $timings = self::$collectedTimings ?? $this->collectTimings();
+
+        if ($timings === []) {
+            return;
+        }
+
+        $this->writeTimings($timings);
+    }
+
+    /**
+     * Collects timings from subscribers or worker temp files.
+     *
+     * @return array<string, float>
+     */
+    private function collectTimings(): array
+    {
+        $runId = Parallel::getGlobal('SHARD_RUN_ID');
+
+        if (is_string($runId)) {
+            return $this->readWorkerTimings($runId);
+        }
+
+        return EnsureShardTimingsAreCollected::timings();
+    }
+
+    /**
+     * Writes the current worker's timing data to a temp file.
+     */
+    private function writeWorkerTimings(): void
+    {
+        $timings = EnsureShardTimingsAreCollected::timings();
+
+        if ($timings === []) {
+            return;
+        }
+
+        $runId = Parallel::getGlobal('SHARD_RUN_ID');
+
+        if (! is_string($runId)) {
+            return;
+        }
+
+        $path = sys_get_temp_dir().DIRECTORY_SEPARATOR.'__pest_sharding_'.$runId.'-'.getmypid().'.json';
+
+        file_put_contents($path, json_encode($timings, JSON_THROW_ON_ERROR));
+    }
+
+    /**
+     * Reads and merges timing data from all worker temp files.
+     *
+     * @return array<string, float>
+     */
+    private function readWorkerTimings(string $runId): array
+    {
+        $pattern = sys_get_temp_dir().DIRECTORY_SEPARATOR.'__pest_sharding_'.$runId.'-*.json';
+        $files = glob($pattern);
+
+        if ($files === false || $files === []) {
+            return [];
+        }
+
+        $merged = [];
+
+        foreach ($files as $file) {
+            $contents = file_get_contents($file);
+
+            if ($contents === false) {
+                continue;
+            }
+
+            $timings = json_decode($contents, true);
+
+            if (is_array($timings)) {
+                $merged = array_merge($merged, $timings);
+            }
+
+            unlink($file);
+        }
+
+        return $merged;
+    }
+
+    /**
+     * Returns the path to shards.json.
+     */
+    private function shardsPath(): string
+    {
+        $testSuite = TestSuite::getInstance();
+
+        return implode(DIRECTORY_SEPARATOR, [$testSuite->rootPath, $testSuite->testPath, '.pest', 'shards.json']);
+    }
+
+    /**
+     * Loads the timings from shards.json.
+     *
+     * @return array<string, float>|null
+     */
+    private function loadShardsFile(): ?array
+    {
+        $path = $this->shardsPath();
+
+        if (! file_exists($path)) {
+            return null;
+        }
+
+        $contents = file_get_contents($path);
+
+        if ($contents === false) {
+            throw new InvalidOption('The [tests/.pest/shards.json] file could not be read. Delete it or run [--update-shards] to regenerate.');
+        }
+
+        $data = json_decode($contents, true);
+
+        if (! is_array($data) || ! isset($data['timings']) || ! is_array($data['timings'])) {
+            throw new InvalidOption('The [tests/.pest/shards.json] file is corrupted. Delete it or run [--update-shards] to regenerate.');
+        }
+
+        return $data['timings'];
+    }
+
+    /**
+     * Partitions tests across shards using the LPT (Longest Processing Time) algorithm.
+     *
+     * @param  list<string>  $tests
+     * @param  array<string, float>  $timings
+     * @return list<list<string>>
+     */
+    private function partitionByTime(array $tests, array $timings, int $total): array
+    {
+        $knownTimings = array_filter(
+            array_map(fn (string $test): ?float => $timings[$test] ?? null, $tests),
+            fn (?float $t): bool => $t !== null,
+        );
+
+        $median = $knownTimings !== [] ? $this->median(array_values($knownTimings)) : 1.0;
+
+        $testsWithTimings = array_map(
+            fn (string $test): array => ['test' => $test, 'time' => $timings[$test] ?? $median],
+            $tests,
+        );
+
+        usort($testsWithTimings, fn (array $a, array $b): int => $b['time'] <=> $a['time']);
+
+        /** @var list<list<string>> */
+        $bins = array_fill(0, $total, []);
+        /** @var non-empty-list<float> */
+        $binTimes = array_fill(0, $total, 0.0);
+
+        foreach ($testsWithTimings as $item) {
+            $minIndex = array_search(min($binTimes), $binTimes, strict: true);
+            assert(is_int($minIndex));
+
+            $bins[$minIndex][] = $item['test'];
+            $binTimes[$minIndex] += $item['time'];
+        }
+
+        return $bins;
+    }
+
+    /**
+     * Calculates the median of an array of floats.
+     *
+     * @param  list<float>  $values
+     */
+    private function median(array $values): float
+    {
+        sort($values);
+
+        $count = count($values);
+        $middle = (int) floor($count / 2);
+
+        if ($count % 2 === 0) {
+            return ($values[$middle - 1] + $values[$middle]) / 2;
+        }
+
+        return $values[$middle];
+    }
+
+    /**
+     * Writes the timings to shards.json.
+     *
+     * @param  array<string, float>  $timings
+     */
+    private function writeTimings(array $timings): void
+    {
+        $path = $this->shardsPath();
+
+        $directory = dirname($path);
+        if (! is_dir($directory)) {
+            mkdir($directory, 0755, true);
+        }
+
+        if (self::$knownTests !== null) {
+            $knownSet = array_flip(self::$knownTests);
+            $timings = array_intersect_key($timings, $knownSet);
+        }
+
+        ksort($timings);
+
+        $canonical = self::$knownTests ?? array_keys($timings);
+        sort($canonical);
+
+        file_put_contents($path, json_encode([
+            'timings' => $timings,
+            'checksum' => md5(implode("\n", $canonical)),
+            'updated_at' => date('c'),
+        ], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES)."\n");
+    }
+
     /**
      * Returns the shard information.
      *

src/Plugins/Snapshot.php

@@ -5,7 +5,6 @@ declare(strict_types=1);
 namespace Pest\Plugins;
 
 use Pest\Contracts\Plugins\HandlesArguments;
-use Pest\Exceptions\InvalidOption;
 use Pest\TestSuite;
 
 /**
@@ -15,21 +14,116 @@ final class Snapshot implements HandlesArguments
 {
     use Concerns\HandleArguments;
 
+    /**
+     * Whether snapshots should be updated on this run.
+     */
+    public static bool $updateSnapshots = false;
+
     /**
      * {@inheritDoc}
      */
     public function handleArguments(array $arguments): array
     {
+        if (Parallel::isWorker() && Parallel::getGlobal('UPDATE_SNAPSHOTS') === true) {
+            self::$updateSnapshots = true;
+
+            return $arguments;
+        }
+
         if (! $this->hasArgument('--update-snapshots', $arguments)) {
             return $arguments;
         }
 
-        if ($this->hasArgument('--parallel', $arguments)) {
+        self::$updateSnapshots = true;
-            throw new InvalidOption('The [--update-snapshots] option is not supported when running in parallel.');
+
+        if ($this->isFullRun($arguments)) {
+            TestSuite::getInstance()->snapshots->flush();
         }
 
-        TestSuite::getInstance()->snapshots->flush();
+        if ($this->hasArgument('--parallel', $arguments) || $this->hasArgument('-p', $arguments)) {
+            Parallel::setGlobal('UPDATE_SNAPSHOTS', true);
+        }
 
         return $this->popArgument('--update-snapshots', $arguments);
     }
+
+    /**
+     * Options that take a value as the next argument (rather than via "=value").
+     *
+     * @var list<string>
+     */
+    private const array FLAGS_WITH_VALUES = [
+        '--filter',
+        '--group',
+        '--exclude-group',
+        '--test-suffix',
+        '--covers',
+        '--uses',
+        '--cache-directory',
+        '--cache-result-file',
+        '--configuration',
+        '--colors',
+        '--test-directory',
+        '--bootstrap',
+        '--order-by',
+        '--random-order-seed',
+        '--log-junit',
+        '--log-teamcity',
+        '--log-events-text',
+        '--log-events-verbose-text',
+        '--coverage-clover',
+        '--coverage-cobertura',
+        '--coverage-crap4j',
+        '--coverage-html',
+        '--coverage-php',
+        '--coverage-text',
+        '--coverage-xml',
+        '--assignee',
+        '--issue',
+        '--ticket',
+        '--pr',
+        '--pull-request',
+        '--retry',
+        '--shard',
+        '--repeat',
+    ];
+
+    /**
+     * Determines whether the command targets the entire suite (no filter, no path).
+     *
+     * @param  array<int, string>  $arguments
+     */
+    private function isFullRun(array $arguments): bool
+    {
+        if ($this->hasArgument('--filter', $arguments)) {
+            return false;
+        }
+
+        $tokens = array_slice($arguments, 1);
+        $skipNext = false;
+
+        foreach ($tokens as $arg) {
+            if ($skipNext) {
+                $skipNext = false;
+
+                continue;
+            }
+
+            if ($arg === '') {
+                continue;
+            }
+
+            if ($arg[0] === '-') {
+                if (in_array($arg, self::FLAGS_WITH_VALUES, true)) {
+                    $skipNext = true;
+                }
+
+                continue;
+            }
+
+            return false;
+        }
+
+        return true;
+    }
 }

src/Plugins/Tia/BaselineSync.php

@@ -0,0 +1,423 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use Composer\InstalledVersions;
+use Pest\Plugins\Tia;
+use Pest\Plugins\Tia\Contracts\State;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Process\Process;
+
+/**
+ * Pulls a team-shared TIA baseline on the first `--tia` run so new
+ * contributors and fresh CI workspaces start in replay mode instead of
+ * paying the ~30s record cost.
+ *
+ * Storage: **workflow artifacts**, not releases. A dedicated CI workflow
+ * (conventionally `.github/workflows/tia-baseline.yml`) runs the full
+ * suite under `--tia` and uploads the `.temp/tia/` directory as a named
+ * artifact (`pest-tia-baseline`) containing `graph.json` +
+ * `coverage.bin`. On dev
+ * machines, this class finds the latest successful run of that workflow
+ * and downloads the artifact via `gh`.
+ *
+ * Why artifacts, not releases:
+ *   - No tag is created → no `push` event cascade into CI workflows.
+ *   - No release event → no deploy workflows tied to `release:published`.
+ *   - Retention is run-scoped and tunable (1-90 days) instead of clobbering
+ *     a single floating tag.
+ *   - Publishing is strictly CI-only: artifacts can't be produced from a
+ *     developer's laptop. This enforces the "CI is the authoritative
+ *     publisher" policy that local-publish paths would otherwise erode.
+ *
+ * Fingerprint validation happens back in `Tia::handleParent` after the
+ * blobs are written: a mismatched environment (different PHP version,
+ * composer.lock, etc.) discards the pulled baseline and falls through to
+ * the regular record path.
+ *
+ * @internal
+ */
+final readonly class BaselineSync
+{
+    /**
+     * Conventional workflow filename teams publish from. Not configurable
+     * for MVP — teams that outgrow the default can set
+     * `PEST_TIA_BASELINE_WORKFLOW` later.
+     */
+    private const string WORKFLOW_FILE = 'tia-baseline.yml';
+
+    /**
+     * Artifact name the workflow uploads under. The artifact is a zip
+     * containing `graph.json` (always) + `coverage.bin` (optional).
+     */
+    private const string ARTIFACT_NAME = 'pest-tia-baseline';
+
+    /**
+     * Asset filenames inside the artifact — mirror the state keys so the
+     * CI publisher and the sync consumer stay in lock-step.
+     */
+    private const string GRAPH_ASSET = Tia::KEY_GRAPH;
+
+    private const string COVERAGE_ASSET = Tia::KEY_COVERAGE_CACHE;
+
+    public function __construct(
+        private State $state,
+        private OutputInterface $output,
+    ) {}
+
+    /**
+     * Detects the repo, fetches the latest baseline artifact, writes its
+     * contents into the TIA state store. Returns true when the graph blob
+     * landed; coverage is best-effort since plain `--tia` (no `--coverage`)
+     * never reads it.
+     */
+    public function fetchIfAvailable(string $projectRoot): bool
+    {
+        $repo = $this->detectGitHubRepo($projectRoot);
+
+        if ($repo === null) {
+            return false;
+        }
+
+        $this->output->writeln(sprintf(
+            '  <fg=cyan>TIA</> fetching baseline from <fg=white>%s</>…',
+            $repo,
+        ));
+
+        $payload = $this->download($repo);
+
+        if ($payload === null) {
+            $this->emitPublishInstructions($repo);
+
+            return false;
+        }
+
+        if (! $this->state->write(Tia::KEY_GRAPH, $payload['graph'])) {
+            return false;
+        }
+
+        if ($payload['coverage'] !== null) {
+            $this->state->write(Tia::KEY_COVERAGE_CACHE, $payload['coverage']);
+        }
+
+        $this->output->writeln(sprintf(
+            '  <fg=green>TIA</> baseline ready (%s).',
+            $this->formatSize(strlen($payload['graph']) + strlen($payload['coverage'] ?? '')),
+        ));
+
+        return true;
+    }
+
+    /**
+     * Prints actionable instructions for publishing a first baseline when
+     * the consumer-side fetch finds nothing.
+     *
+     * Behaviour splits on environment:
+     *   - **CI:** a single line. The current run is almost certainly *the*
+     *     publisher (it's what this workflow does by definition), so
+     *     printing the whole recipe again is redundant and noisy.
+     *   - **Local:** the full recipe, adapted to Laravel's pre-test steps
+     *     (`.env.example` copy + `artisan key:generate`) when the framework
+     *     is present. Generic PHP projects get a slimmer skeleton.
+     */
+    private function emitPublishInstructions(string $repo): void
+    {
+        if ($this->isCi()) {
+            $this->output->writeln(
+                '  <fg=yellow>TIA</> no baseline yet — this run will produce one.',
+            );
+
+            return;
+        }
+
+        $yaml = $this->isLaravel()
+            ? $this->laravelWorkflowYaml()
+            : $this->genericWorkflowYaml();
+
+        $preamble = [
+            '  <fg=yellow>TIA</> no baseline published yet — recording locally.',
+            '',
+            '  To share the baseline with your team, add this workflow to the repo:',
+            '',
+            '    <fg=cyan>.github/workflows/tia-baseline.yml</>',
+            '',
+        ];
+
+        $indentedYaml = array_map(
+            static fn (string $line): string => '      '.$line,
+            explode("\n", $yaml),
+        );
+
+        $trailer = [
+            '',
+            sprintf('  Commit, push, then run once:  <fg=cyan>gh workflow run tia-baseline.yml -R %s</>', $repo),
+            '  Details: <fg=gray>https://pestphp.com/docs/tia/ci</>',
+            '',
+        ];
+
+        $this->output->writeln([...$preamble, ...$indentedYaml, ...$trailer]);
+    }
+
+    /**
+     * True when running inside a CI provider. Conservative list — only the
+     * three providers Pest formally supports / sees in the wild. `CI=true`
+     * alone is ambiguous (users set it locally too) so we require a
+     * provider-specific flag.
+     */
+    private function isCi(): bool
+    {
+        return getenv('GITHUB_ACTIONS') === 'true'
+            || getenv('GITLAB_CI') === 'true'
+            || getenv('CIRCLECI') === 'true';
+    }
+
+    private function isLaravel(): bool
+    {
+        return class_exists(InstalledVersions::class)
+            && InstalledVersions::isInstalled('laravel/framework');
+    }
+
+    /**
+     * Laravel projects need a populated `.env` and a generated `APP_KEY`
+     * before the first boot, otherwise `Illuminate\Encryption\MissingAppKeyException`
+     * fires during `setUp`. Include the standard pre-test dance plus the
+     * extension set typical Laravel apps rely on.
+     */
+    private function laravelWorkflowYaml(): string
+    {
+        return <<<'YAML'
+name: TIA Baseline
+on:
+  push: { branches: [main] }
+  schedule: [{ cron: '0 3 * * *' }]
+  workflow_dispatch:
+jobs:
+  baseline:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          coverage: xdebug
+          extensions: json, dom, curl, libxml, mbstring, zip, pdo, pdo_sqlite, sqlite3, bcmath, intl
+      - run: cp .env.example .env
+      - run: composer install --no-interaction --prefer-dist
+      - run: php artisan key:generate
+      - run: ./vendor/bin/pest --parallel --tia --coverage
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pest-tia-baseline
+          path: vendor/pestphp/pest/.temp/tia/
+          retention-days: 30
+YAML;
+    }
+
+    private function genericWorkflowYaml(): string
+    {
+        return <<<'YAML'
+name: TIA Baseline
+on:
+  push: { branches: [main] }
+  schedule: [{ cron: '0 3 * * *' }]
+  workflow_dispatch:
+jobs:
+  baseline:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: shivammathur/setup-php@v2
+        with: { php-version: '8.4', coverage: xdebug }
+      - run: composer install --no-interaction --prefer-dist
+      - run: ./vendor/bin/pest --parallel --tia --coverage
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pest-tia-baseline
+          path: vendor/pestphp/pest/.temp/tia/
+          retention-days: 30
+YAML;
+    }
+
+    /**
+     * Parses `.git/config` for the `origin` remote and extracts
+     * `org/repo`. Supports the two URL flavours git emits out of the box.
+     * Non-GitHub remotes (GitLab, Bitbucket, self-hosted) → null, which
+     * silently opts the repo out of auto-sync.
+     */
+    private function detectGitHubRepo(string $projectRoot): ?string
+    {
+        $gitConfig = $projectRoot.DIRECTORY_SEPARATOR.'.git'.DIRECTORY_SEPARATOR.'config';
+
+        if (! is_file($gitConfig)) {
+            return null;
+        }
+
+        $content = @file_get_contents($gitConfig);
+
+        if ($content === false) {
+            return null;
+        }
+
+        // Find the `[remote "origin"]` section and the first `url` line
+        // inside it. Tolerates INI whitespace quirks (tabs, CRLF).
+        if (preg_match('/\[remote "origin"\][^\[]*?url\s*=\s*(\S+)/s', $content, $match) !== 1) {
+            return null;
+        }
+
+        $url = $match[1];
+
+        // SSH: git@github.com:org/repo(.git)
+        if (preg_match('#^git@github\.com:([\w.-]+/[\w.-]+?)(?:\.git)?$#', $url, $m) === 1) {
+            return $m[1];
+        }
+
+        // HTTPS: https://github.com/org/repo(.git) (optional trailing slash)
+        if (preg_match('#^https?://github\.com/([\w.-]+/[\w.-]+?)(?:\.git)?/?$#', $url, $m) === 1) {
+            return $m[1];
+        }
+
+        return null;
+    }
+
+    /**
+     * Two-step fetch: find the latest successful run of the baseline
+     * workflow, then download the named artifact from it. Returns
+     * `['graph' => bytes, 'coverage' => bytes|null]` on success, or null
+     * if `gh` is unavailable, the workflow hasn't run yet, the artifact
+     * is missing, or any shell step fails.
+     *
+     * @return array{graph: string, coverage: ?string}|null
+     */
+    private function download(string $repo): ?array
+    {
+        if (! $this->commandExists('gh')) {
+            return null;
+        }
+
+        $runId = $this->latestSuccessfulRunId($repo);
+
+        if ($runId === null) {
+            return null;
+        }
+
+        $tmpDir = sys_get_temp_dir().DIRECTORY_SEPARATOR.'pest-tia-'.bin2hex(random_bytes(4));
+
+        if (! @mkdir($tmpDir, 0755, true) && ! is_dir($tmpDir)) {
+            return null;
+        }
+
+        $process = new Process([
+            'gh', 'run', 'download', $runId,
+            '-R', $repo,
+            '-n', self::ARTIFACT_NAME,
+            '-D', $tmpDir,
+        ]);
+        $process->setTimeout(120.0);
+        $process->run();
+
+        if (! $process->isSuccessful()) {
+            $this->cleanup($tmpDir);
+
+            return null;
+        }
+
+        $graphPath = $tmpDir.DIRECTORY_SEPARATOR.self::GRAPH_ASSET;
+        $coveragePath = $tmpDir.DIRECTORY_SEPARATOR.self::COVERAGE_ASSET;
+
+        $graph = is_file($graphPath) ? @file_get_contents($graphPath) : false;
+
+        if ($graph === false) {
+            $this->cleanup($tmpDir);
+
+            return null;
+        }
+
+        $coverage = is_file($coveragePath) ? @file_get_contents($coveragePath) : false;
+
+        $this->cleanup($tmpDir);
+
+        return [
+            'graph' => $graph,
+            'coverage' => $coverage === false ? null : $coverage,
+        ];
+    }
+
+    /**
+     * Queries GitHub for the most recent successful run of the baseline
+     * workflow. `--jq '.[0].databaseId // empty'` coerces "no runs found"
+     * into an empty string, which we map to null.
+     */
+    private function latestSuccessfulRunId(string $repo): ?string
+    {
+        $process = new Process([
+            'gh', 'run', 'list',
+            '-R', $repo,
+            '--workflow', self::WORKFLOW_FILE,
+            '--status', 'success',
+            '--limit', '1',
+            '--json', 'databaseId',
+            '--jq', '.[0].databaseId // empty',
+        ]);
+        $process->setTimeout(30.0);
+        $process->run();
+
+        if (! $process->isSuccessful()) {
+            return null;
+        }
+
+        $runId = trim($process->getOutput());
+
+        return $runId === '' ? null : $runId;
+    }
+
+    private function commandExists(string $cmd): bool
+    {
+        $probe = new Process(['command', '-v', $cmd]);
+        $probe->run();
+
+        if ($probe->isSuccessful()) {
+            return true;
+        }
+
+        $which = new Process(['which', $cmd]);
+        $which->run();
+
+        return $which->isSuccessful();
+    }
+
+    private function cleanup(string $dir): void
+    {
+        if (! is_dir($dir)) {
+            return;
+        }
+
+        $entries = glob($dir.DIRECTORY_SEPARATOR.'*');
+
+        if ($entries !== false) {
+            foreach ($entries as $entry) {
+                if (is_file($entry)) {
+                    @unlink($entry);
+                }
+            }
+        }
+
+        @rmdir($dir);
+    }
+
+    private function formatSize(int $bytes): string
+    {
+        if ($bytes >= 1024 * 1024) {
+            return sprintf('%.1f MB', $bytes / 1024 / 1024);
+        }
+
+        if ($bytes >= 1024) {
+            return sprintf('%.1f KB', $bytes / 1024);
+        }
+
+        return $bytes.' B';
+    }
+}

src/Plugins/Tia/Bootstrapper.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use Pest\Contracts\Bootstrapper as BootstrapperContract;
+use Pest\Plugins\Tia\Contracts\State;
+use Pest\Support\Container;
+
+/**
+ * Plugin-level container registrations for TIA. Runs as part of Kernel's
+ * bootstrapper chain so Tia's own service graph is set up without Kernel
+ * having to know about any of its internals.
+ *
+ * Most Tia services (`Recorder`, `CoverageCollector`, `WatchPatterns`,
+ * `ResultCollector`, `BaselineSync`) are auto-buildable — Pest's container
+ * resolves them lazily via constructor reflection. The only service that
+ * requires an explicit binding is the `State` contract, because the
+ * filesystem implementation needs a root-directory string that reflection
+ * can't infer.
+ *
+ * @internal
+ */
+final readonly class Bootstrapper implements BootstrapperContract
+{
+    public function __construct(private Container $container) {}
+
+    public function boot(): void
+    {
+        $this->container->add(State::class, new FileState($this->tempDir()));
+    }
+
+    /**
+     * TIA's own subdirectory under Pest's `.temp/`. Keeping every TIA blob
+     * in a single folder (`.temp/tia/`) avoids the `tia-`-prefix salad
+     * alongside PHPUnit's unrelated files (coverage.php, test-results,
+     * code-coverage/) and makes the CI artifact-upload path a single
+     * directory instead of a list of individual files.
+     */
+    private function tempDir(): string
+    {
+        return __DIR__
+            .DIRECTORY_SEPARATOR.'..'
+            .DIRECTORY_SEPARATOR.'..'
+            .DIRECTORY_SEPARATOR.'..'
+            .DIRECTORY_SEPARATOR.'.temp'
+            .DIRECTORY_SEPARATOR.'tia';
+    }
+}

src/Plugins/Tia/ChangedFiles.php

@@ -0,0 +1,339 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use Symfony\Component\Process\Process;
+
+/**
+ * Detects files that changed between the last recorded TIA run and the
+ * current working tree.
+ *
+ * Strategy:
+ *   1. If we have a `recordedAtSha`, `git diff <sha>..HEAD` captures committed
+ *      changes on top of the recording point.
+ *   2. `git status --short` captures unstaged + staged + untracked changes on
+ *      top of that.
+ *
+ * We return relative paths to the project root. Deletions are included so the
+ * caller can decide whether to invalidate: a deleted source file may still
+ * appear in the graph and should mark its dependents as affected.
+ *
+ * @internal
+ */
+final readonly class ChangedFiles
+{
+    public function __construct(private string $projectRoot) {}
+
+    /**
+     * @return array<int, string>|null `null` when git is unavailable, or when
+     *                                 the recorded SHA is no longer reachable
+     *                                 from HEAD (rebase / force-push) — in
+     *                                 that case the graph should be rebuilt.
+     */
+    /**
+     * Removes files whose current content hash matches the snapshot from the
+     * last `--tia` run. Used to ignore "dirty but unchanged" files — a file
+     * that git still reports as modified but whose content is bit-identical
+     * to the previous TIA invocation.
+     *
+     * @param  array<int, string>  $files  project-relative paths.
+     * @param  array<string, string>  $lastRunTree  path → content hash from last run.
+     * @return array<int, string>
+     */
+    public function filterUnchangedSinceLastRun(array $files, array $lastRunTree): array
+    {
+        if ($lastRunTree === []) {
+            return $files;
+        }
+
+        // Union: `$files` (what git currently reports) + every path that was
+        // dirty last run. The second set matters for reverts — when a user
+        // undoes a local edit, the file matches HEAD again and git reports
+        // it clean, so it would never enter `$files`. But it has genuinely
+        // changed vs the snapshot we captured during the bad run, so it
+        // must be checked.
+        $candidates = array_fill_keys($files, true);
+
+        foreach (array_keys($lastRunTree) as $snapshotted) {
+            $candidates[$snapshotted] = true;
+        }
+
+        $remaining = [];
+
+        foreach (array_keys($candidates) as $file) {
+            $snapshot = $lastRunTree[$file] ?? null;
+            $absolute = $this->projectRoot.DIRECTORY_SEPARATOR.$file;
+            $exists = is_file($absolute);
+
+            if ($snapshot === null) {
+                // File wasn't in last-run tree at all — trust git's signal.
+                $remaining[] = $file;
+
+                continue;
+            }
+
+            if (! $exists) {
+                // Missing now. If the snapshot recorded it as absent too
+                // (sentinel ''), state is identical to last run — unchanged.
+                // Otherwise it was present last run and got deleted since.
+                if ($snapshot !== '') {
+                    $remaining[] = $file;
+                }
+
+                continue;
+            }
+
+            $hash = @hash_file('xxh128', $absolute);
+
+            if ($hash === false || $hash !== $snapshot) {
+                $remaining[] = $file;
+            }
+        }
+
+        return $remaining;
+    }
+
+    /**
+     * Computes content hashes for the given project-relative files. Used to
+     * snapshot the working tree after a successful run so the next run can
+     * detect which files are actually different.
+     *
+     * @param  array<int, string>  $files
+     * @return array<string, string> path → xxh128 content hash
+     */
+    public function snapshotTree(array $files): array
+    {
+        $out = [];
+
+        foreach ($files as $file) {
+            $absolute = $this->projectRoot.DIRECTORY_SEPARATOR.$file;
+
+            if (! is_file($absolute)) {
+                // Record the deletion with an empty-string sentinel so the
+                // next run recognises "still deleted" as unchanged rather
+                // than re-flagging the file as a fresh change.
+                $out[$file] = '';
+
+                continue;
+            }
+
+            $hash = @hash_file('xxh128', $absolute);
+
+            if ($hash !== false) {
+                $out[$file] = $hash;
+            }
+        }
+
+        return $out;
+    }
+
+    /**
+     * @return array<int, string>|null `null` when git is unavailable, or when
+     *                                 the recorded SHA is no longer reachable
+     *                                 from HEAD (rebase / force-push).
+     */
+    public function since(?string $sha): ?array
+    {
+        if (! $this->gitAvailable()) {
+            return null;
+        }
+
+        $files = [];
+
+        if ($sha !== null && $sha !== '') {
+            if (! $this->shaIsReachable($sha)) {
+                return null;
+            }
+
+            $files = array_merge($files, $this->diffSinceSha($sha));
+        }
+
+        $files = array_merge($files, $this->workingTreeChanges());
+
+        // Normalise + dedupe, filtering out paths that can never belong to the
+        // graph: vendor (caught by the fingerprint instead), cache dirs, and
+        // anything starting with a dot we don't care about.
+        $unique = [];
+
+        foreach ($files as $file) {
+            if ($file === '') {
+                continue;
+            }
+            if ($this->shouldIgnore($file)) {
+                continue;
+            }
+            $unique[$file] = true;
+        }
+
+        return array_keys($unique);
+    }
+
+    private function shouldIgnore(string $path): bool
+    {
+        static $prefixes = [
+            '.pest/',
+            '.phpunit.cache/',
+            '.phpunit.result.cache',
+            'vendor/',
+            'node_modules/',
+        ];
+
+        foreach ($prefixes as $prefix) {
+            if (str_starts_with($path, (string) $prefix)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    public function currentBranch(): ?string
+    {
+        if (! $this->gitAvailable()) {
+            return null;
+        }
+
+        $process = new Process(['git', 'rev-parse', '--abbrev-ref', 'HEAD'], $this->projectRoot);
+        $process->run();
+
+        if (! $process->isSuccessful()) {
+            return null;
+        }
+
+        $branch = trim($process->getOutput());
+
+        return $branch === '' || $branch === 'HEAD' ? null : $branch;
+    }
+
+    public function gitAvailable(): bool
+    {
+        $process = new Process(['git', 'rev-parse', '--git-dir'], $this->projectRoot);
+        $process->run();
+
+        return $process->isSuccessful();
+    }
+
+    private function shaIsReachable(string $sha): bool
+    {
+        $process = new Process(
+            ['git', 'merge-base', '--is-ancestor', $sha, 'HEAD'],
+            $this->projectRoot,
+        );
+        $process->run();
+
+        // Exit 0 → ancestor; 1 → not ancestor; anything else → git error
+        // (e.g. unknown commit after a rebase/gc). Treat non-zero as
+        // "unreachable" and force a rebuild.
+        return $process->getExitCode() === 0;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function diffSinceSha(string $sha): array
+    {
+        $process = new Process(
+            ['git', 'diff', '--name-only', $sha.'..HEAD'],
+            $this->projectRoot,
+        );
+        $process->run();
+
+        if (! $process->isSuccessful()) {
+            return [];
+        }
+
+        return $this->splitLines($process->getOutput());
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function workingTreeChanges(): array
+    {
+        // `-z` produces NUL-terminated records with no path quoting, so paths
+        // that contain spaces, tabs, unicode or other special characters
+        // are passed through verbatim. Without `-z`, git wraps such paths in
+        // quotes with backslash escapes, which would corrupt our lookup keys.
+        //
+        // Record format: `XY <SP> <path> <NUL>` for most entries, and
+        // `R  <new> <NUL> <orig> <NUL>` for renames/copies (two NUL-separated
+        // fields).
+        $process = new Process(
+            ['git', 'status', '--porcelain', '-z', '--untracked-files=all'],
+            $this->projectRoot,
+        );
+        $process->run();
+
+        if (! $process->isSuccessful()) {
+            return [];
+        }
+
+        $output = $process->getOutput();
+
+        if ($output === '') {
+            return [];
+        }
+
+        $records = explode("\x00", rtrim($output, "\x00"));
+        $files = [];
+        $count = count($records);
+
+        for ($i = 0; $i < $count; $i++) {
+            $record = $records[$i];
+
+            if (strlen($record) < 4) {
+                continue;
+            }
+
+            $status = substr($record, 0, 2);
+            $path = substr($record, 3);
+
+            // Renames/copies emit two records: the new path first, then the
+            // original. Consume both.
+            if ($status[0] === 'R' || $status[0] === 'C') {
+                $files[] = $path;
+
+                if (isset($records[$i + 1]) && $records[$i + 1] !== '') {
+                    $files[] = $records[$i + 1];
+                    $i++;
+                }
+
+                continue;
+            }
+
+            $files[] = $path;
+        }
+
+        return $files;
+    }
+
+    public function currentSha(): ?string
+    {
+        if (! $this->gitAvailable()) {
+            return null;
+        }
+
+        $process = new Process(['git', 'rev-parse', 'HEAD'], $this->projectRoot);
+        $process->run();
+
+        if (! $process->isSuccessful()) {
+            return null;
+        }
+
+        $sha = trim($process->getOutput());
+
+        return $sha === '' ? null : $sha;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function splitLines(string $output): array
+    {
+        $lines = preg_split('/\R+/', trim($output), flags: PREG_SPLIT_NO_EMPTY);
+
+        return $lines === false ? [] : $lines;
+    }
+}

src/Plugins/Tia/Configuration.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use Pest\Support\Container;
+
+/**
+ * User-facing TIA configuration, returned by `pest()->tia()`.
+ *
+ * Usage in `tests/Pest.php`:
+ *
+ *     pest()->tia()->watch([
+ *         'resources/js/**\/*.tsx' => 'tests/Browser',
+ *         'public/build/**\/*'     => 'tests/Browser',
+ *     ]);
+ *
+ * Patterns are merged with the built-in defaults (config, routes, views,
+ * frontend assets, migrations). Duplicate glob keys overwrite the default
+ * mapping so users can redirect a pattern to a narrower directory.
+ *
+ * @internal
+ */
+final class Configuration
+{
+    /**
+     * Adds watch-pattern → test-directory mappings that supplement (or
+     * override) the built-in defaults.
+     *
+     * @param  array<string, string>  $patterns  glob → project-relative test dir
+     * @return $this
+     */
+    public function watch(array $patterns): self
+    {
+        /** @var WatchPatterns $watchPatterns */
+        $watchPatterns = Container::getInstance()->get(WatchPatterns::class);
+        $watchPatterns->add($patterns);
+
+        return $this;
+    }
+}

src/Plugins/Tia/Contracts/State.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia\Contracts;
+
+/**
+ * Storage contract for TIA's persistent state (graph, baselines, affected
+ * set, worker partials, coverage snapshots). Modelled as a flat key/value
+ * store of raw byte blobs so implementations can sit on top of whatever
+ * backend fits — a directory, a shared cache, a remote object store — and
+ * TIA's logic stays identical.
+ *
+ * @internal
+ */
+interface State
+{
+    /**
+     * Returns the stored blob for `$key`, or `null` when the key is unset
+     * or cannot be read.
+     */
+    public function read(string $key): ?string;
+
+    /**
+     * Atomically stores `$content` under `$key`. Existing value (if any) is
+     * replaced. Implementations SHOULD guarantee that concurrent readers
+     * never observe partial writes.
+     */
+    public function write(string $key, string $content): bool;
+
+    /**
+     * Removes `$key`. Returns true whether or not the key existed beforehand
+     * — callers should treat a `true` result as "the key is now absent",
+     * not "the key was present and has been removed."
+     */
+    public function delete(string $key): bool;
+
+    public function exists(string $key): bool;
+
+    /**
+     * Returns every key whose name starts with `$prefix`. Used to collect
+     * paratest worker partials (`worker-edges-<token>.json`, etc.) without
+     * exposing backend-specific glob semantics.
+     *
+     * @return list<string>
+     */
+    public function keysWithPrefix(string $prefix): array;
+}

src/Plugins/Tia/CoverageCollector.php

@@ -0,0 +1,152 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use PHPUnit\Runner\CodeCoverage as PhpUnitCodeCoverage;
+use ReflectionClass;
+use Throwable;
+
+/**
+ * Extracts per-test file coverage from PHPUnit's shared `CodeCoverage`
+ * instance. Used when TIA piggybacks on `--coverage` instead of starting
+ * its own driver session — both share the same PCOV / Xdebug state, so
+ * running two recorders in parallel would corrupt each other's data.
+ *
+ * PHPUnit tags every coverage sample with the current test's id
+ * (`$test->valueObjectForEvents()->id()`, e.g. `Foo\BarTest::baz`). The
+ * per-file / per-line coverage map therefore already carries everything
+ * we need to rebuild TIA edges at the end of the run.
+ *
+ * @internal
+ */
+final class CoverageCollector
+{
+    /**
+     * Cached `className → test file` lookups. Class reflection is cheap
+     * individually but the record run can visit tens of thousands of
+     * samples, so the cache matters.
+     *
+     * @var array<string, string|null>
+     */
+    private array $classFileCache = [];
+
+    /**
+     * Rebuilds the same `absolute test file → list<absolute source file>`
+     * shape that `Recorder::perTestFiles()` exposes, so callers can treat
+     * the two collectors interchangeably when feeding the graph.
+     *
+     * @return array<string, array<int, string>>
+     */
+    public function perTestFiles(): array
+    {
+        if (! PhpUnitCodeCoverage::instance()->isActive()) {
+            return [];
+        }
+
+        try {
+            $lineCoverage = PhpUnitCodeCoverage::instance()
+                ->codeCoverage()
+                ->getData()
+                ->lineCoverage();
+        } catch (Throwable) {
+            return [];
+        }
+
+        /** @var array<string, array<string, true>> $edges */
+        $edges = [];
+
+        foreach ($lineCoverage as $sourceFile => $lines) {
+            // Collect the set of tests that hit any line in this file once,
+            // then emit one edge per (testFile, sourceFile) pair. Walking
+            // the lines per test would re-resolve the test file repeatedly.
+            $testIds = [];
+
+            foreach ($lines as $hits) {
+                if ($hits === null) {
+                    continue;
+                }
+
+                foreach ($hits as $id) {
+                    $testIds[$id] = true;
+                }
+            }
+
+            foreach (array_keys($testIds) as $testId) {
+                $testFile = $this->testIdToFile($testId);
+
+                if ($testFile === null) {
+                    continue;
+                }
+
+                $edges[$testFile][$sourceFile] = true;
+            }
+        }
+
+        $out = [];
+
+        foreach ($edges as $testFile => $sources) {
+            $out[$testFile] = array_keys($sources);
+        }
+
+        return $out;
+    }
+
+    public function reset(): void
+    {
+        $this->classFileCache = [];
+    }
+
+    private function testIdToFile(string $testId): ?string
+    {
+        // PHPUnit's test id is `ClassName::methodName` with an optional
+        // `#dataSetName` suffix for data-provider runs. Strip the dataset
+        // part — we only need the class.
+        $hash = strpos($testId, '#');
+        $identifier = $hash === false ? $testId : substr($testId, 0, $hash);
+
+        if (! str_contains($identifier, '::')) {
+            return null;
+        }
+
+        [$className] = explode('::', $identifier, 2);
+
+        if (array_key_exists($className, $this->classFileCache)) {
+            return $this->classFileCache[$className];
+        }
+
+        $file = $this->resolveClassFile($className);
+        $this->classFileCache[$className] = $file;
+
+        return $file;
+    }
+
+    private function resolveClassFile(string $className): ?string
+    {
+        if (! class_exists($className, false)) {
+            return null;
+        }
+
+        $reflection = new ReflectionClass($className);
+
+        // Pest's eval'd test classes expose the original `.php` path on a
+        // static `$__filename`. The eval'd class itself has no file of its
+        // own, so prefer this property when present.
+        if ($reflection->hasProperty('__filename')) {
+            $property = $reflection->getProperty('__filename');
+
+            if ($property->isStatic()) {
+                $value = $property->getValue();
+
+                if (is_string($value)) {
+                    return $value;
+                }
+            }
+        }
+
+        $file = $reflection->getFileName();
+
+        return is_string($file) ? $file : null;
+    }
+}

src/Plugins/Tia/CoverageMerger.php

@@ -0,0 +1,187 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use Pest\Plugins\Tia;
+use Pest\Plugins\Tia\Contracts\State;
+use Pest\Support\Container;
+use SebastianBergmann\CodeCoverage\CodeCoverage;
+use Throwable;
+
+/**
+ * Merges the current run's PHPUnit coverage into a cached full-suite
+ * snapshot so `--tia --coverage` can produce a complete report after
+ * executing only the affected tests.
+ *
+ * Invoked from `Pest\Support\Coverage::report()` right before the coverage
+ * file is consumed. A marker dropped by the `Tia` plugin gates the
+ * behaviour — plain `--coverage` runs (no `--tia`) leave the marker absent
+ * and therefore keep their existing semantics.
+ *
+ * Algorithm
+ * ---------
+ * The PHPUnit coverage PHP file unserialises to a `CodeCoverage` object.
+ * Its `ProcessedCodeCoverageData` stores, per source file, per line, the
+ * list of test IDs that covered that line. We:
+ *
+ *   1. Load the cached snapshot from `State` (serialised bytes).
+ *   2. Strip every test id that re-ran this time from the cached map —
+ *      the tests that ran now are the ones whose attribution is fresh.
+ *   3. Merge the current run into the stripped cached snapshot via
+ *      `CodeCoverage::merge()`.
+ *   4. Write the merged result back to the report path (so Pest's report
+ *      generator sees the full suite) and back into `State` (for the
+ *      next invocation).
+ *
+ * If no cache exists yet (first `--tia --coverage` run on this machine)
+ * we serialise the current object and save it — nothing to merge yet.
+ *
+ * @internal
+ */
+final class CoverageMerger
+{
+    public static function applyIfMarked(string $reportPath): void
+    {
+        $state = self::state();
+
+        if (! $state instanceof State || ! $state->exists(Tia::KEY_COVERAGE_MARKER)) {
+            return;
+        }
+
+        $state->delete(Tia::KEY_COVERAGE_MARKER);
+
+        $cachedBytes = $state->read(Tia::KEY_COVERAGE_CACHE);
+
+        if ($cachedBytes === null) {
+            // First `--tia --coverage` run: nothing cached yet, so the
+            // current file already represents the full suite. Capture it
+            // verbatim (as serialised bytes) for next time.
+            $current = self::requireCoverage($reportPath);
+
+            if ($current instanceof CodeCoverage) {
+                $state->write(Tia::KEY_COVERAGE_CACHE, serialize($current));
+            }
+
+            return;
+        }
+
+        $cached = self::unserializeCoverage($cachedBytes);
+        $current = self::requireCoverage($reportPath);
+
+        if (! $cached instanceof CodeCoverage || ! $current instanceof CodeCoverage) {
+            return;
+        }
+
+        self::stripCurrentTestsFromCached($cached, $current);
+
+        $cached->merge($current);
+
+        $serialised = serialize($cached);
+
+        // Write back to the PHPUnit-style `.cov` path so the report reader
+        // can `require` it, and to the state cache for the next run.
+        @file_put_contents(
+            $reportPath,
+            '<?php return unserialize('.var_export($serialised, true).");\n",
+        );
+        $state->write(Tia::KEY_COVERAGE_CACHE, $serialised);
+    }
+
+    /**
+     * Removes from `$cached`'s per-line test attribution any test id that
+     * appears in `$current`. Those tests just ran, so the fresh slice is
+     * authoritative — keeping stale attribution in the cache would claim
+     * a test still covers a line it no longer touches.
+     */
+    private static function stripCurrentTestsFromCached(CodeCoverage $cached, CodeCoverage $current): void
+    {
+        $currentIds = self::collectTestIds($current);
+
+        if ($currentIds === []) {
+            return;
+        }
+
+        $cachedData = $cached->getData();
+        $lineCoverage = $cachedData->lineCoverage();
+
+        foreach ($lineCoverage as $file => $lines) {
+            foreach ($lines as $line => $ids) {
+                if ($ids === null) {
+                    continue;
+                }
+                if ($ids === []) {
+                    continue;
+                }
+                $filtered = array_values(array_diff($ids, $currentIds));
+
+                if ($filtered !== $ids) {
+                    $lineCoverage[$file][$line] = $filtered;
+                }
+            }
+        }
+
+        $cachedData->setLineCoverage($lineCoverage);
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private static function collectTestIds(CodeCoverage $coverage): array
+    {
+        $ids = [];
+
+        foreach ($coverage->getData()->lineCoverage() as $lines) {
+            foreach ($lines as $hits) {
+                if ($hits === null) {
+                    continue;
+                }
+
+                foreach ($hits as $id) {
+                    $ids[$id] = true;
+                }
+            }
+        }
+
+        return array_keys($ids);
+    }
+
+    private static function state(): ?State
+    {
+        try {
+            $state = Container::getInstance()->get(State::class);
+        } catch (Throwable) {
+            return null;
+        }
+
+        return $state instanceof State ? $state : null;
+    }
+
+    private static function requireCoverage(string $reportPath): ?CodeCoverage
+    {
+        if (! is_file($reportPath)) {
+            return null;
+        }
+
+        try {
+            /** @var mixed $value */
+            $value = require $reportPath;
+        } catch (Throwable) {
+            return null;
+        }
+
+        return $value instanceof CodeCoverage ? $value : null;
+    }
+
+    private static function unserializeCoverage(string $bytes): ?CodeCoverage
+    {
+        try {
+            $value = @unserialize($bytes);
+        } catch (Throwable) {
+            return null;
+        }
+
+        return $value instanceof CodeCoverage ? $value : null;
+    }
+}

src/Plugins/Tia/FileState.php

@@ -0,0 +1,150 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use Pest\Plugins\Tia\Contracts\State;
+
+/**
+ * Filesystem-backed implementation of the TIA `State` contract. Each key
+ * maps verbatim to a file name under `$rootDir`, so existing `.temp/*.json`
+ * layouts are preserved exactly.
+ *
+ * The root directory is created lazily on first write — callers don't have
+ * to pre-provision it, and reads against a missing directory simply return
+ * `null` rather than throwing.
+ *
+ * @internal
+ */
+final readonly class FileState implements State
+{
+    /**
+     * Configured root. May not exist on disk yet; resolved + created on
+     * the first write. Keeping the raw string lets the instance be built
+     * before Pest's temp dir has been materialised.
+     */
+    private string $rootDir;
+
+    public function __construct(string $rootDir)
+    {
+        $this->rootDir = rtrim($rootDir, DIRECTORY_SEPARATOR);
+    }
+
+    public function read(string $key): ?string
+    {
+        $path = $this->pathFor($key);
+
+        if (! is_file($path)) {
+            return null;
+        }
+
+        $bytes = @file_get_contents($path);
+
+        return $bytes === false ? null : $bytes;
+    }
+
+    public function write(string $key, string $content): bool
+    {
+        if (! $this->ensureRoot()) {
+            return false;
+        }
+
+        $path = $this->pathFor($key);
+        $tmp = $path.'.'.bin2hex(random_bytes(4)).'.tmp';
+
+        if (@file_put_contents($tmp, $content) === false) {
+            return false;
+        }
+
+        // Atomic rename — on POSIX filesystems this is a single-step
+        // replacement, so concurrent readers never see a half-written file.
+        if (! @rename($tmp, $path)) {
+            @unlink($tmp);
+
+            return false;
+        }
+
+        return true;
+    }
+
+    public function delete(string $key): bool
+    {
+        $path = $this->pathFor($key);
+
+        if (! is_file($path)) {
+            return true;
+        }
+
+        return @unlink($path);
+    }
+
+    public function exists(string $key): bool
+    {
+        return is_file($this->pathFor($key));
+    }
+
+    public function keysWithPrefix(string $prefix): array
+    {
+        $root = $this->resolvedRoot();
+
+        if ($root === null) {
+            return [];
+        }
+
+        $pattern = $root.DIRECTORY_SEPARATOR.$prefix.'*';
+        $matches = glob($pattern);
+
+        if ($matches === false) {
+            return [];
+        }
+
+        $keys = [];
+
+        foreach ($matches as $path) {
+            $keys[] = basename($path);
+        }
+
+        return $keys;
+    }
+
+    /**
+     * Absolute path for `$key`. Not part of the interface — used by the
+     * coverage merger and similar callers that need direct filesystem
+     * access (e.g. `require` on a cached PHP file). Consumers that only
+     * deal in bytes should go through `read()` / `write()`.
+     */
+    public function pathFor(string $key): string
+    {
+        return $this->rootDir.DIRECTORY_SEPARATOR.$key;
+    }
+
+    /**
+     * Returns the resolved root if it exists already, otherwise `null`.
+     * Used by read-side helpers so they don't eagerly create the directory
+     * just to find nothing inside.
+     */
+    private function resolvedRoot(): ?string
+    {
+        $resolved = @realpath($this->rootDir);
+
+        return $resolved === false ? null : $resolved;
+    }
+
+    /**
+     * Creates the root dir on demand. Returns false only when creation
+     * fails and the directory still isn't there afterwards.
+     */
+    private function ensureRoot(): bool
+    {
+        if (is_dir($this->rootDir)) {
+            return true;
+        }
+
+        if (@mkdir($this->rootDir, 0755, true)) {
+            return true;
+        }
+
+        return is_dir($this->rootDir);
+    }
+}

src/Plugins/Tia/Fingerprint.php

@@ -0,0 +1,223 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+/**
+ * Captures environmental inputs that, when changed, may make the TIA graph
+ * or its recorded results stale. The fingerprint is split into two buckets:
+ *
+ *   - **structural** — describes what the graph's *edges* were recorded
+ *     against. If any of these drift (`composer.lock`, `tests/Pest.php`,
+ *     Pest's factory codegen, etc.) the edges themselves are potentially
+ *     wrong and the graph must rebuild from scratch.
+ *   - **environmental** — describes the *runtime* the results were captured
+ *     on (PHP minor, extension set, Pest version). Drift here means the
+ *     edges are still trustworthy, but the cached per-test results (pass/
+ *     fail/time) may not reproduce on this machine. Tia's handler drops the
+ *     branch's results + coverage cache and re-runs to freshen them, rather
+ *     than re-recording from scratch.
+ *
+ * Legacy flat-shape graphs (schema ≤ 3) are read as structurally stale and
+ * rebuilt on first load; the schema bump in the structural bucket takes
+ * care of that automatically.
+ *
+ * @internal
+ */
+final readonly class Fingerprint
+{
+    // Bump this whenever the set of inputs or the hash algorithm changes,
+    // so older graphs are invalidated automatically.
+    private const int SCHEMA_VERSION = 4;
+
+    /**
+     * @return array{
+     *     structural: array<string, int|string|null>,
+     *     environmental: array<string, string|null>,
+     * }
+     */
+    public static function compute(string $projectRoot): array
+    {
+        return [
+            'structural' => [
+                'schema' => self::SCHEMA_VERSION,
+                'composer_lock' => self::hashIfExists($projectRoot.'/composer.lock'),
+                'phpunit_xml' => self::hashIfExists($projectRoot.'/phpunit.xml'),
+                'phpunit_xml_dist' => self::hashIfExists($projectRoot.'/phpunit.xml.dist'),
+                'pest_php' => self::hashIfExists($projectRoot.'/tests/Pest.php'),
+                // Pest's generated classes bake the code-generation logic
+                // in — if TestCaseFactory changes (new attribute, different
+                // method signature, etc.) every previously-recorded edge is
+                // stale. Hashing the factory sources makes path-repo /
+                // dev-main installs automatically rebuild their graphs when
+                // Pest itself is edited.
+                'pest_factory' => self::hashIfExists(__DIR__.'/../../Factories/TestCaseFactory.php'),
+                'pest_method_factory' => self::hashIfExists(__DIR__.'/../../Factories/TestCaseMethodFactory.php'),
+            ],
+            'environmental' => [
+                // PHP **minor** only (8.4, not 8.4.19) — CI's resolved patch
+                // almost never matches a dev's Herd/Homebrew install, and
+                // the patch rarely changes anything test-visible.
+                'php_minor' => PHP_MAJOR_VERSION.'.'.PHP_MINOR_VERSION,
+                'extensions' => self::extensionsFingerprint(),
+                'pest' => self::readPestVersion($projectRoot),
+            ],
+        ];
+    }
+
+    /**
+     * True when the structural buckets match. Drift here means the edges
+     * are potentially wrong; caller should discard the graph and rebuild.
+     *
+     * @param  array<string, mixed>  $a
+     * @param  array<string, mixed>  $b
+     */
+    public static function structuralMatches(array $a, array $b): bool
+    {
+        $aStructural = self::structuralOnly($a);
+        $bStructural = self::structuralOnly($b);
+
+        ksort($aStructural);
+        ksort($bStructural);
+
+        return $aStructural === $bStructural;
+    }
+
+    /**
+     * Returns a list of field names that drifted between the stored and
+     * current environmental fingerprints. Empty list = no drift. Caller
+     * uses this to print a human-readable warning and to decide whether
+     * per-test results should be dropped (any drift → yes).
+     *
+     * @param  array<string, mixed>  $stored
+     * @param  array<string, mixed>  $current
+     * @return list<string>
+     */
+    public static function environmentalDrift(array $stored, array $current): array
+    {
+        $a = self::environmentalOnly($stored);
+        $b = self::environmentalOnly($current);
+
+        $drifts = [];
+
+        foreach ($a as $key => $value) {
+            if (($b[$key] ?? null) !== $value) {
+                $drifts[] = $key;
+            }
+        }
+
+        foreach ($b as $key => $value) {
+            if (! array_key_exists($key, $a) && $value !== null) {
+                $drifts[] = $key;
+            }
+        }
+
+        return array_values(array_unique($drifts));
+    }
+
+    /**
+     * @param  array<string, mixed>  $fingerprint
+     * @return array<string, mixed>
+     */
+    private static function structuralOnly(array $fingerprint): array
+    {
+        return self::bucket($fingerprint, 'structural');
+    }
+
+    /**
+     * @param  array<string, mixed>  $fingerprint
+     * @return array<string, mixed>
+     */
+    private static function environmentalOnly(array $fingerprint): array
+    {
+        return self::bucket($fingerprint, 'environmental');
+    }
+
+    /**
+     * Returns `$fingerprint[$key]` as an `array<string, mixed>` if it exists
+     * and is an array, otherwise empty. Legacy flat-shape fingerprints
+     * (schema ≤ 3) return empty here, which makes `structuralMatches` fail
+     * and the caller rebuild — the clean migration path.
+     *
+     * @param  array<string, mixed>  $fingerprint
+     * @return array<string, mixed>
+     */
+    private static function bucket(array $fingerprint, string $key): array
+    {
+        $raw = $fingerprint[$key] ?? null;
+
+        if (! is_array($raw)) {
+            return [];
+        }
+
+        $normalised = [];
+
+        foreach ($raw as $k => $v) {
+            if (is_string($k)) {
+                $normalised[$k] = $v;
+            }
+        }
+
+        return $normalised;
+    }
+
+    private static function hashIfExists(string $path): ?string
+    {
+        if (! is_file($path)) {
+            return null;
+        }
+
+        $hash = @hash_file('xxh128', $path);
+
+        return $hash === false ? null : $hash;
+    }
+
+    /**
+     * Deterministic hash of the PHP extension set: `ext-name@version` pairs
+     * sorted alphabetically and joined.
+     */
+    private static function extensionsFingerprint(): string
+    {
+        $extensions = get_loaded_extensions();
+        sort($extensions);
+
+        $parts = [];
+
+        foreach ($extensions as $name) {
+            $version = phpversion($name);
+            $parts[] = $name.'@'.($version === false ? '?' : $version);
+        }
+
+        return hash('xxh128', implode("\n", $parts));
+    }
+
+    private static function readPestVersion(string $projectRoot): string
+    {
+        $installed = $projectRoot.'/vendor/composer/installed.json';
+
+        if (! is_file($installed)) {
+            return 'unknown';
+        }
+
+        $raw = @file_get_contents($installed);
+
+        if ($raw === false) {
+            return 'unknown';
+        }
+
+        $data = json_decode($raw, true);
+
+        if (! is_array($data) || ! isset($data['packages']) || ! is_array($data['packages'])) {
+            return 'unknown';
+        }
+
+        foreach ($data['packages'] as $package) {
+            if (is_array($package) && ($package['name'] ?? null) === 'pestphp/pest') {
+                return (string) ($package['version'] ?? 'unknown');
+            }
+        }
+
+        return 'unknown';
+    }
+}

src/Plugins/Tia/Graph.php

@@ -0,0 +1,514 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use Pest\Support\Container;
+use PHPUnit\Framework\TestStatus\TestStatus;
+
+/**
+ * File-level Test Impact Analysis graph.
+ *
+ * Persists the mapping `test_file → set<source_file>` so that subsequent runs
+ * can skip tests whose dependencies have not changed. Paths are stored relative
+ * to the project root and source files are deduplicated via an index so that
+ * the on-disk JSON stays compact for large suites.
+ *
+ * @internal
+ */
+final class Graph
+{
+    /**
+     * Relative path of each known source file, indexed by numeric id.
+     *
+     * @var array<int, string>
+     */
+    private array $files = [];
+
+    /**
+     * Reverse lookup: source file → numeric id.
+     *
+     * @var array<string, int>
+     */
+    private array $fileIds = [];
+
+    /**
+     * Edges: test file (relative) → list of source file ids.
+     *
+     * @var array<string, array<int, int>>
+     */
+    private array $edges = [];
+
+    /**
+     * Environment fingerprint captured at record time.
+     *
+     * @var array<string, mixed>
+     */
+    private array $fingerprint = [];
+
+    /**
+     * Per-branch baselines. Each branch independently tracks:
+     *   - `sha`     — last HEAD at which `--tia` ran on this branch
+     *   - `tree`    — content hashes of modified files at that point
+     *   - `results` — per-test status + message + time
+     *
+     * Graph edges (test → source) stay shared across branches because
+     * structure doesn't change per branch. Only run-state is per-branch so
+     * a failing test on one branch doesn't poison another branch's replay.
+     *
+     * @var array<string, array{
+     *     sha: ?string,
+     *     tree: array<string, string>,
+     *     results: array<string, array{status: int, message: string, time: float, assertions?: int}>
+     * }>
+     */
+    private array $baselines = [];
+
+    /**
+     * Canonicalised project root. Resolved through `realpath()` so paths
+     * captured by coverage drivers (always real filesystem targets) match
+     * regardless of whether the user's CWD is a symlink or has trailing
+     * separators.
+     */
+    private readonly string $projectRoot;
+
+    public function __construct(string $projectRoot)
+    {
+        $real = @realpath($projectRoot);
+
+        $this->projectRoot = $real !== false ? $real : $projectRoot;
+    }
+
+    /**
+     * Records that a test file depends on the given source file.
+     */
+    public function link(string $testFile, string $sourceFile): void
+    {
+        $testRel = $this->relative($testFile);
+        $sourceRel = $this->relative($sourceFile);
+
+        if ($sourceRel === null || $testRel === null) {
+            return;
+        }
+
+        if (! isset($this->fileIds[$sourceRel])) {
+            $id = count($this->files);
+            $this->files[$id] = $sourceRel;
+            $this->fileIds[$sourceRel] = $id;
+        }
+
+        $this->edges[$testRel][] = $this->fileIds[$sourceRel];
+    }
+
+    /**
+     * Returns the set of test files whose dependencies intersect $changedFiles.
+     *
+     * Two resolution paths:
+     *   1. **Coverage edges** — test depends on a PHP source file that changed.
+     *   2. **Watch patterns** — a non-PHP file (JS, CSS, config, …) matches a
+     *      glob that maps to a test directory; every test under that directory
+     *      is affected.
+     *
+     * @param  array<int, string>  $changedFiles  Absolute or relative paths.
+     * @return array<int, string> Relative test file paths.
+     */
+    public function affected(array $changedFiles): array
+    {
+        // Normalise all changed paths once.
+        $normalised = [];
+
+        foreach ($changedFiles as $file) {
+            $rel = $this->relative($file);
+
+            if ($rel !== null) {
+                $normalised[] = $rel;
+            }
+        }
+
+        // 1. Coverage-edge lookup (PHP → PHP).
+        $changedIds = [];
+        $unknownSourceDirs = [];
+
+        foreach ($normalised as $rel) {
+            if (isset($this->fileIds[$rel])) {
+                $changedIds[$this->fileIds[$rel]] = true;
+            } elseif (str_ends_with($rel, '.php') && ! str_starts_with($rel, 'tests/')) {
+                // Source PHP file unknown to the graph — might be a new file
+                // that only exists on this branch (graph inherited from main).
+                // Track its directory for the sibling heuristic (step 3).
+                $unknownSourceDirs[dirname($rel)] = true;
+            }
+        }
+
+        $affectedSet = [];
+
+        foreach ($this->edges as $testFile => $ids) {
+            foreach ($ids as $id) {
+                if (isset($changedIds[$id])) {
+                    $affectedSet[$testFile] = true;
+
+                    break;
+                }
+            }
+        }
+
+        // 2. Watch-pattern lookup (non-PHP assets → test directories).
+        /** @var WatchPatterns $watchPatterns */
+        $watchPatterns = Container::getInstance()->get(WatchPatterns::class);
+
+        $dirs = $watchPatterns->matchedDirectories($this->projectRoot, $normalised);
+        $allTestFiles = array_keys($this->edges);
+
+        foreach ($watchPatterns->testsUnderDirectories($dirs, $allTestFiles) as $testFile) {
+            $affectedSet[$testFile] = true;
+        }
+
+        // 3. Sibling heuristic for unknown source files.
+        //
+        // When a PHP source file is unknown to the graph (no test depends on
+        // it), it is either genuinely untested OR it was added on a branch
+        // whose graph was inherited from another branch (e.g. main). In the
+        // latter case the graph simply never saw the file.
+        //
+        // To avoid silent misses: find tests that already cover ANY file in
+        // the same directory. If `app/Models/OrderItem.php` is unknown but
+        // `app/Models/Order.php` is covered by `OrderTest`, run `OrderTest`
+        // — it likely exercises sibling files in the same module.
+        //
+        // This over-runs slightly (sibling may be unrelated) but never
+        // under-runs. And once the test executes, its coverage captures the
+        // new file → graph self-heals for next run.
+        if ($unknownSourceDirs !== []) {
+            foreach ($this->edges as $testFile => $ids) {
+                if (isset($affectedSet[$testFile])) {
+                    continue;
+                }
+
+                foreach ($ids as $id) {
+                    if (! isset($this->files[$id])) {
+                        continue;
+                    }
+
+                    $depDir = dirname($this->files[$id]);
+
+                    if (isset($unknownSourceDirs[$depDir])) {
+                        $affectedSet[$testFile] = true;
+
+                        break;
+                    }
+                }
+            }
+        }
+
+        return array_keys($affectedSet);
+    }
+
+    /**
+     * Returns `true` if the given test file has any recorded dependencies.
+     */
+    public function knowsTest(string $testFile): bool
+    {
+        $rel = $this->relative($testFile);
+
+        return $rel !== null && isset($this->edges[$rel]);
+    }
+
+    /**
+     * @return array<int, string> All project-relative test files the graph knows.
+     */
+    public function allTestFiles(): array
+    {
+        return array_keys($this->edges);
+    }
+
+    /**
+     * @param  array<string, mixed>  $fingerprint
+     */
+    public function setFingerprint(array $fingerprint): void
+    {
+        $this->fingerprint = $fingerprint;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function fingerprint(): array
+    {
+        return $this->fingerprint;
+    }
+
+    /**
+     * Returns the SHA the given branch last ran against, or falls back to
+     * `$fallbackBranch` (typically `main`) when this branch has no baseline
+     * yet. That way a freshly-created feature branch inherits main's
+     * baseline on its first run.
+     */
+    public function recordedAtSha(string $branch, string $fallbackBranch = 'main'): ?string
+    {
+        $baseline = $this->baselineFor($branch, $fallbackBranch);
+
+        return $baseline['sha'];
+    }
+
+    public function setRecordedAtSha(string $branch, ?string $sha): void
+    {
+        $this->ensureBaseline($branch);
+        $this->baselines[$branch]['sha'] = $sha;
+    }
+
+    public function setResult(string $branch, string $testId, int $status, string $message, float $time, int $assertions = 0): void
+    {
+        $this->ensureBaseline($branch);
+        $this->baselines[$branch]['results'][$testId] = [
+            'status' => $status,
+            'message' => $message,
+            'time' => $time,
+            'assertions' => $assertions,
+        ];
+    }
+
+    /**
+     * Returns the cached assertion count for a test, or `null` if unknown.
+     * Callers use this to feed `addToAssertionCount()` at replay time so
+     * the "Tests: N passed (M assertions)" banner matches the recorded run
+     * instead of defaulting to 1 assertion per test.
+     */
+    public function getAssertions(string $branch, string $testId, string $fallbackBranch = 'main'): ?int
+    {
+        $baseline = $this->baselineFor($branch, $fallbackBranch);
+
+        if (! isset($baseline['results'][$testId]['assertions'])) {
+            return null;
+        }
+
+        return $baseline['results'][$testId]['assertions'];
+    }
+
+    public function getResult(string $branch, string $testId, string $fallbackBranch = 'main'): ?TestStatus
+    {
+        $baseline = $this->baselineFor($branch, $fallbackBranch);
+
+        if (! isset($baseline['results'][$testId])) {
+            return null;
+        }
+
+        $r = $baseline['results'][$testId];
+
+        // PHPUnit's `TestStatus::from(int)` ignores messages, so reconstruct
+        // each variant via its specific factory. Keeps the stored message
+        // intact (important for skips/failures shown to the user).
+        return match ($r['status']) {
+            0 => TestStatus::success(),
+            1 => TestStatus::skipped($r['message']),
+            2 => TestStatus::incomplete($r['message']),
+            3 => TestStatus::notice($r['message']),
+            4 => TestStatus::deprecation($r['message']),
+            5 => TestStatus::risky($r['message']),
+            6 => TestStatus::warning($r['message']),
+            7 => TestStatus::failure($r['message']),
+            8 => TestStatus::error($r['message']),
+            default => TestStatus::unknown(),
+        };
+    }
+
+    /**
+     * @param  array<string, string>  $tree  project-relative path → content hash
+     */
+    public function setLastRunTree(string $branch, array $tree): void
+    {
+        $this->ensureBaseline($branch);
+        $this->baselines[$branch]['tree'] = $tree;
+    }
+
+    /**
+     * Wipes cached per-test results for the given branch. Edges and tree
+     * snapshot stay intact — the graph still describes the code correctly,
+     * only the "what happened last time" data is reset. Used on
+     * environmental fingerprint drift: the edges were recorded elsewhere
+     * (e.g. CI) so they're still valid, but the results aren't trustworthy
+     * on this machine until the tests re-run here.
+     */
+    public function clearResults(string $branch): void
+    {
+        $this->ensureBaseline($branch);
+        $this->baselines[$branch]['results'] = [];
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function lastRunTree(string $branch, string $fallbackBranch = 'main'): array
+    {
+        return $this->baselineFor($branch, $fallbackBranch)['tree'];
+    }
+
+    /**
+     * @return array{sha: ?string, tree: array<string, string>, results: array<string, array{status: int, message: string, time: float, assertions?: int}>}
+     */
+    private function baselineFor(string $branch, string $fallbackBranch): array
+    {
+        if (isset($this->baselines[$branch])) {
+            return $this->baselines[$branch];
+        }
+
+        if ($branch !== $fallbackBranch && isset($this->baselines[$fallbackBranch])) {
+            return $this->baselines[$fallbackBranch];
+        }
+
+        return ['sha' => null, 'tree' => [], 'results' => []];
+    }
+
+    private function ensureBaseline(string $branch): void
+    {
+        if (! isset($this->baselines[$branch])) {
+            $this->baselines[$branch] = ['sha' => null, 'tree' => [], 'results' => []];
+        }
+    }
+
+    /**
+     * Replaces edges for the given test files. Used during a partial record
+     * run so that existing edges for other tests are preserved.
+     *
+     * @param  array<string, array<int, string>>  $testToFiles
+     */
+    public function replaceEdges(array $testToFiles): void
+    {
+        foreach ($testToFiles as $testFile => $sources) {
+            $testRel = $this->relative($testFile);
+
+            if ($testRel === null) {
+                continue;
+            }
+
+            $this->edges[$testRel] = [];
+
+            foreach ($sources as $source) {
+                $this->link($testFile, $source);
+            }
+
+            // Deduplicate ids for this test.
+            $this->edges[$testRel] = array_values(array_unique($this->edges[$testRel]));
+        }
+    }
+
+    /**
+     * Drops edges whose test file no longer exists on disk. Prevents the graph
+     * from keeping stale entries for deleted / renamed tests that would later
+     * be flagged as affected and confuse PHPUnit's discovery.
+     */
+    public function pruneMissingTests(): void
+    {
+        $root = rtrim($this->projectRoot, DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR;
+
+        foreach (array_keys($this->edges) as $testRel) {
+            if (! is_file($root.$testRel)) {
+                unset($this->edges[$testRel]);
+            }
+        }
+    }
+
+    /**
+     * Rebuilds a graph from its JSON representation. Returns `null` when
+     * the payload is missing, unreadable, or schema-incompatible. Separated
+     * from transport (state backend, file, etc.) so tests can feed bytes
+     * directly without touching disk.
+     */
+    public static function decode(string $json, string $projectRoot): ?self
+    {
+        $data = json_decode($json, true);
+
+        if (! is_array($data) || ($data['schema'] ?? null) !== 1) {
+            return null;
+        }
+
+        $graph = new self($projectRoot);
+        $graph->fingerprint = is_array($data['fingerprint'] ?? null) ? $data['fingerprint'] : [];
+        $graph->files = is_array($data['files'] ?? null) ? array_values($data['files']) : [];
+        $graph->fileIds = array_flip($graph->files);
+        $graph->edges = is_array($data['edges'] ?? null) ? $data['edges'] : [];
+        $graph->baselines = is_array($data['baselines'] ?? null) ? $data['baselines'] : [];
+
+        return $graph;
+    }
+
+    /**
+     * Serialises the graph to its JSON on-disk form. Returns `null` if the
+     * payload can't be encoded (extremely rare — pathological UTF-8 only).
+     * Persistence is the caller's responsibility: write the returned bytes
+     * through whatever `State` implementation is in play.
+     */
+    public function encode(): ?string
+    {
+        $payload = [
+            'schema' => 1,
+            'fingerprint' => $this->fingerprint,
+            'files' => $this->files,
+            'edges' => $this->edges,
+            'baselines' => $this->baselines,
+        ];
+
+        $json = json_encode($payload, JSON_UNESCAPED_SLASHES);
+
+        return $json === false ? null : $json;
+    }
+
+    /**
+     * Normalises a path to be relative to the project root; returns `null` for
+     * paths we should ignore (outside the project, unknown, virtual, vendor).
+     *
+     * Accepts both absolute paths (from Xdebug/PCOV coverage) and
+     * project-relative paths (from `git diff`) — we normalise without relying
+     * on `realpath()` of relative paths because the current working directory
+     * is not guaranteed to be the project root.
+     */
+    private function relative(string $path): ?string
+    {
+        if ($path === '' || $path === 'unknown') {
+            return null;
+        }
+
+        if (str_contains($path, "eval()'d")) {
+            return null;
+        }
+
+        $root = rtrim($this->projectRoot, DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR;
+
+        $isAbsolute = str_starts_with($path, DIRECTORY_SEPARATOR)
+            || (strlen($path) >= 2 && $path[1] === ':'); // Windows drive
+
+        if ($isAbsolute) {
+            $real = @realpath($path);
+
+            if ($real === false) {
+                $real = $path;
+            }
+
+            if (! str_starts_with($real, $root)) {
+                return null;
+            }
+
+            // Always normalise to forward slashes. Windows' native separator
+            // would otherwise produce keys that never match paths reported
+            // by `git` (which always uses forward slashes).
+            $relative = str_replace(DIRECTORY_SEPARATOR, '/', substr($real, strlen($root)));
+        } else {
+            // Normalise directory separators and strip any "./" prefix.
+            $relative = str_replace(DIRECTORY_SEPARATOR, '/', $path);
+
+            while (str_starts_with($relative, './')) {
+                $relative = substr($relative, 2);
+            }
+        }
+
+        // Vendor packages are pinned by composer.lock. Any upgrade bumps the
+        // fingerprint and invalidates the graph wholesale, so there is no
+        // reason to track individual vendor files — doing so inflates the
+        // graph by orders of magnitude on Laravel-style projects.
+        if (str_starts_with($relative, 'vendor/')) {
+            return null;
+        }
+
+        return $relative;
+    }
+}

src/Plugins/Tia/Recorder.php

@@ -0,0 +1,229 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use ReflectionClass;
+
+/**
+ * Captures per-test file coverage using the PCOV driver.
+ *
+ * Acts as a singleton because PCOV has a single global collection state and
+ * the recorder is wired into PHPUnit through two distinct subscribers
+ * (`Prepared` / `Finished`) that must share context.
+ *
+ * @internal
+ */
+final class Recorder
+{
+    /**
+     * Test file currently being recorded, or `null` when idle.
+     */
+    private ?string $currentTestFile = null;
+
+    /**
+     * Aggregated map: absolute test file → set<absolute source file>.
+     *
+     * @var array<string, array<string, true>>
+     */
+    private array $perTestFiles = [];
+
+    /**
+     * Cached class → test file resolution.
+     *
+     * @var array<string, string|null>
+     */
+    private array $classFileCache = [];
+
+    private bool $active = false;
+
+    private bool $driverChecked = false;
+
+    private bool $driverAvailable = false;
+
+    private string $driver = 'none';
+
+    public function activate(): void
+    {
+        $this->active = true;
+    }
+
+    public function isActive(): bool
+    {
+        return $this->active;
+    }
+
+    public function driverAvailable(): bool
+    {
+        if (! $this->driverChecked) {
+            if (function_exists('pcov\\start')) {
+                $this->driver = 'pcov';
+                $this->driverAvailable = true;
+            } elseif (function_exists('xdebug_start_code_coverage')) {
+                // Xdebug is loaded. Probe whether coverage mode is active by
+                // attempting a start — it emits E_WARNING when the mode is off.
+                // We capture the warning via a temporary error handler.
+                $probeOk = true;
+                set_error_handler(static function () use (&$probeOk): bool {
+                    $probeOk = false;
+
+                    return true;
+                });
+                \xdebug_start_code_coverage();
+                restore_error_handler();
+
+                if ($probeOk) {
+                    \xdebug_stop_code_coverage(false);
+                    $this->driver = 'xdebug';
+                    $this->driverAvailable = true;
+                }
+            }
+
+            $this->driverChecked = true;
+        }
+
+        return $this->driverAvailable;
+    }
+
+    public function driver(): string
+    {
+        $this->driverAvailable();
+
+        return $this->driver;
+    }
+
+    public function beginTest(string $className, string $methodName, string $fallbackFile): void
+    {
+        if (! $this->active || ! $this->driverAvailable()) {
+            return;
+        }
+
+        $file = $this->resolveTestFile($className, $fallbackFile);
+
+        if ($file === null) {
+            return;
+        }
+
+        $this->currentTestFile = $file;
+
+        if ($this->driver === 'pcov') {
+            \pcov\clear();
+            \pcov\start();
+
+            return;
+        }
+
+        // Xdebug
+        \xdebug_start_code_coverage();
+    }
+
+    public function endTest(): void
+    {
+        if (! $this->active || ! $this->driverAvailable() || $this->currentTestFile === null) {
+            return;
+        }
+
+        if ($this->driver === 'pcov') {
+            \pcov\stop();
+            /** @var array<string, mixed> $data */
+            $data = \pcov\collect(\pcov\inclusive);
+        } else {
+            /** @var array<string, mixed> $data */
+            $data = \xdebug_get_code_coverage();
+            // `true` resets Xdebug's internal buffer so the next `start()`
+            // does not accumulate earlier tests' coverage into the current
+            // one — otherwise the graph becomes progressively polluted.
+            \xdebug_stop_code_coverage(true);
+        }
+
+        foreach (array_keys($data) as $sourceFile) {
+            $this->perTestFiles[$this->currentTestFile][$sourceFile] = true;
+        }
+
+        $this->currentTestFile = null;
+    }
+
+    /**
+     * @return array<string, array<int, string>> absolute test file → list of absolute source files.
+     */
+    public function perTestFiles(): array
+    {
+        $out = [];
+
+        foreach ($this->perTestFiles as $testFile => $sources) {
+            $out[$testFile] = array_keys($sources);
+        }
+
+        return $out;
+    }
+
+    private function resolveTestFile(string $className, string $fallbackFile): ?string
+    {
+        if (array_key_exists($className, $this->classFileCache)) {
+            $file = $this->classFileCache[$className];
+        } else {
+            $file = $this->readPestFilename($className);
+            $this->classFileCache[$className] = $file;
+        }
+
+        if ($file !== null) {
+            return $file;
+        }
+
+        if ($fallbackFile !== '' && $fallbackFile !== 'unknown' && ! str_contains($fallbackFile, "eval()'d")) {
+            return $fallbackFile;
+        }
+
+        return null;
+    }
+
+    /**
+     * Resolves the file that *defines* the test class.
+     *
+     * Order of preference:
+     *   1. Pest's generated `$__filename` static — the original `*.php` file
+     *      containing the `test()` calls (the eval'd class itself has no file).
+     *   2. `ReflectionClass::getFileName()` — the concrete class's file. This
+     *      is intentionally more specific than `ReflectionMethod::getFileName()`
+     *      (which would return the *trait* file for methods brought in via
+     *      `uses SharedTestBehavior`).
+     */
+    private function readPestFilename(string $className): ?string
+    {
+        if (! class_exists($className, false)) {
+            return null;
+        }
+
+        $reflection = new ReflectionClass($className);
+
+        if ($reflection->hasProperty('__filename')) {
+            $property = $reflection->getProperty('__filename');
+
+            if ($property->isStatic()) {
+                $value = $property->getValue();
+
+                if (is_string($value)) {
+                    return $value;
+                }
+            }
+        }
+
+        $file = $reflection->getFileName();
+
+        return is_string($file) ? $file : null;
+    }
+
+    /**
+     * Clears all captured state. Useful for long-running hosts (daemons,
+     * PHP-FPM, watchers) that invoke Pest multiple times in a single process
+     * — without this, coverage from run N would bleed into run N+1.
+     */
+    public function reset(): void
+    {
+        $this->currentTestFile = null;
+        $this->perTestFiles = [];
+        $this->classFileCache = [];
+        $this->active = false;
+    }
+}

src/Plugins/Tia/ResultCollector.php

@@ -0,0 +1,155 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+/**
+ * Collects per-test status + message during the run so the graph can persist
+ * them for faithful replay. PHPUnit's own result cache discards messages
+ * during serialisation — this collector retains them.
+ *
+ * @internal
+ */
+final class ResultCollector
+{
+    /**
+     * @var array<string, array{status: int, message: string, time: float, assertions: int}>
+     */
+    private array $results = [];
+
+    private ?string $currentTestId = null;
+
+    private ?float $startTime = null;
+
+    public function testPrepared(string $testId): void
+    {
+        $this->currentTestId = $testId;
+        $this->startTime = microtime(true);
+    }
+
+    public function testPassed(): void
+    {
+        if ($this->currentTestId === null) {
+            return;
+        }
+
+        $this->record(0, '');
+    }
+
+    public function testFailed(string $message): void
+    {
+        if ($this->currentTestId === null) {
+            return;
+        }
+
+        $this->record(7, $message);
+    }
+
+    public function testErrored(string $message): void
+    {
+        if ($this->currentTestId === null) {
+            return;
+        }
+
+        $this->record(8, $message);
+    }
+
+    public function testSkipped(string $message): void
+    {
+        if ($this->currentTestId === null) {
+            return;
+        }
+
+        $this->record(1, $message);
+    }
+
+    public function testIncomplete(string $message): void
+    {
+        if ($this->currentTestId === null) {
+            return;
+        }
+
+        $this->record(2, $message);
+    }
+
+    public function testRisky(string $message): void
+    {
+        if ($this->currentTestId === null) {
+            return;
+        }
+
+        $this->record(5, $message);
+    }
+
+    /**
+     * @return array<string, array{status: int, message: string, time: float, assertions: int}>
+     */
+    public function all(): array
+    {
+        return $this->results;
+    }
+
+    public function recordAssertions(string $testId, int $assertions): void
+    {
+        if (isset($this->results[$testId])) {
+            $this->results[$testId]['assertions'] = $assertions;
+        }
+    }
+
+    /**
+     * Injects externally-collected results (e.g. partials flushed by parallel
+     * workers) into this collector so the parent can persist them in the same
+     * snapshot pass as non-parallel runs.
+     *
+     * @param  array<string, array{status: int, message: string, time: float, assertions: int}>  $results
+     */
+    public function merge(array $results): void
+    {
+        foreach ($results as $testId => $result) {
+            $this->results[$testId] = $result;
+        }
+    }
+
+    public function reset(): void
+    {
+        $this->results = [];
+        $this->currentTestId = null;
+        $this->startTime = null;
+    }
+
+    /**
+     * Called by the Finished subscriber after a test's outcome + assertion
+     * events have all fired. Clears the "currently recording" pointer so
+     * the next test's events don't get mis-attributed.
+     */
+    public function finishTest(): void
+    {
+        $this->currentTestId = null;
+        $this->startTime = null;
+    }
+
+    private function record(int $status, string $message): void
+    {
+        if ($this->currentTestId === null) {
+            return;
+        }
+
+        $time = $this->startTime !== null
+            ? round(microtime(true) - $this->startTime, 3)
+            : 0.0;
+
+        // PHPUnit can fire more than one outcome event per test — the
+        // canonical case is a risky pass (`Passed` then `ConsideredRisky`).
+        // Last-wins semantics preserve the most specific status; the
+        // existing assertion count (if any) survives the overwrite.
+        $existing = $this->results[$this->currentTestId] ?? null;
+
+        $this->results[$this->currentTestId] = [
+            'status' => $status,
+            'message' => $message,
+            'time' => $time,
+            'assertions' => $existing['assertions'] ?? 0,
+        ];
+    }
+}

src/Plugins/Tia/WatchDefaults/Browser.php

@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia\WatchDefaults;
+
+use Composer\InstalledVersions;
+use Pest\Browser\Support\BrowserTestIdentifier;
+use Pest\Factories\TestCaseFactory;
+use Pest\TestSuite;
+
+/**
+ * Watch patterns for frontend assets that affect browser tests.
+ *
+ * Uses `BrowserTestIdentifier` from pest-plugin-browser (if installed) to
+ * auto-discover directories containing browser tests. Falls back to the
+ * `tests/Browser` convention when the plugin is absent.
+ *
+ * @internal
+ */
+final readonly class Browser implements WatchDefault
+{
+    public function applicable(): bool
+    {
+        // Browser tests can exist in any PHP project. We only activate when
+        // there is an actual `tests/Browser` directory OR pest-plugin-browser
+        // is installed.
+        return class_exists(InstalledVersions::class)
+            && InstalledVersions::isInstalled('pestphp/pest-plugin-browser');
+    }
+
+    public function defaults(string $projectRoot, string $testPath): array
+    {
+        $browserDirs = $this->detectBrowserTestDirs($projectRoot, $testPath);
+
+        $globs = [
+            'resources/js/**/*.js',
+            'resources/js/**/*.ts',
+            'resources/js/**/*.tsx',
+            'resources/js/**/*.jsx',
+            'resources/js/**/*.vue',
+            'resources/js/**/*.svelte',
+            'resources/css/**/*.css',
+            'resources/css/**/*.scss',
+            'resources/css/**/*.less',
+            // Vite / Webpack build output that browser tests may consume.
+            'public/build/**/*.js',
+            'public/build/**/*.css',
+        ];
+
+        $patterns = [];
+
+        foreach ($globs as $glob) {
+            $patterns[$glob] = $browserDirs;
+        }
+
+        return $patterns;
+    }
+
+    /**
+     * @return array<int, string>
+     */
+    private function detectBrowserTestDirs(string $projectRoot, string $testPath): array
+    {
+        $dirs = [];
+
+        $candidate = $testPath.'/Browser';
+
+        if (is_dir($projectRoot.DIRECTORY_SEPARATOR.$candidate)) {
+            $dirs[] = $candidate;
+        }
+
+        // Scan TestRepository via BrowserTestIdentifier if pest-plugin-browser
+        // is installed to find tests using `visit()` outside the conventional
+        // Browser/ folder.
+        if (class_exists(BrowserTestIdentifier::class)) {
+            $repo = TestSuite::getInstance()->tests;
+
+            foreach ($repo->getFilenames() as $filename) {
+                $factory = $repo->get($filename);
+
+                if (! $factory instanceof TestCaseFactory) {
+                    continue;
+                }
+
+                foreach ($factory->methods as $method) {
+                    if (BrowserTestIdentifier::isBrowserTest($method)) {
+                        $rel = $this->fileRelative($projectRoot, $filename);
+
+                        if ($rel !== null) {
+                            $dirs[] = dirname($rel);
+                        }
+
+                        break;
+                    }
+                }
+            }
+        }
+
+        return array_values(array_unique($dirs === [] ? [$testPath] : $dirs));
+    }
+
+    private function fileRelative(string $projectRoot, string $path): ?string
+    {
+        $real = @realpath($path);
+
+        if ($real === false) {
+            $real = $path;
+        }
+
+        $root = rtrim($projectRoot, DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR;
+
+        if (! str_starts_with($real, $root)) {
+            return null;
+        }
+
+        return str_replace(DIRECTORY_SEPARATOR, '/', substr($real, strlen($root)));
+    }
+}

src/Plugins/Tia/WatchDefaults/Inertia.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia\WatchDefaults;
+
+use Composer\InstalledVersions;
+
+/**
+ * Watch patterns for Inertia.js projects (Laravel or otherwise).
+ *
+ * Inertia bridges PHP controllers with JS/TS page components. A change to
+ * a React / Vue / Svelte page can break assertions in browser tests or
+ * Inertia-specific feature tests.
+ *
+ * @internal
+ */
+final readonly class Inertia implements WatchDefault
+{
+    public function applicable(): bool
+    {
+        return class_exists(InstalledVersions::class)
+            && (InstalledVersions::isInstalled('inertiajs/inertia-laravel')
+                || InstalledVersions::isInstalled('rompetomp/inertia-bundle'));
+    }
+
+    public function defaults(string $projectRoot, string $testPath): array
+    {
+        $browserDir = is_dir($projectRoot.DIRECTORY_SEPARATOR.$testPath.'/Browser')
+            ? $testPath.'/Browser'
+            : $testPath;
+
+        return [
+            // Inertia page components (React / Vue / Svelte).
+            'resources/js/Pages/**/*.vue' => [$testPath, $browserDir],
+            'resources/js/Pages/**/*.tsx' => [$testPath, $browserDir],
+            'resources/js/Pages/**/*.jsx' => [$testPath, $browserDir],
+            'resources/js/Pages/**/*.svelte' => [$testPath, $browserDir],
+
+            // Shared layouts / components consumed by pages.
+            'resources/js/Layouts/**/*.vue' => [$browserDir],
+            'resources/js/Layouts/**/*.tsx' => [$browserDir],
+            'resources/js/Components/**/*.vue' => [$browserDir],
+            'resources/js/Components/**/*.tsx' => [$browserDir],
+
+            // SSR entry point.
+            'resources/js/ssr.js' => [$browserDir],
+            'resources/js/ssr.ts' => [$browserDir],
+            'resources/js/app.js' => [$browserDir],
+            'resources/js/app.ts' => [$browserDir],
+        ];
+    }
+}

src/Plugins/Tia/WatchDefaults/Laravel.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia\WatchDefaults;
+
+use Composer\InstalledVersions;
+
+/**
+ * Watch patterns for Laravel projects.
+ *
+ * Laravel boots the entire application inside `setUp()` (before PHPUnit's
+ * `Prepared` event where TIA's coverage window opens). That means PHP files
+ * loaded during boot — config, routes, service providers, migrations — are
+ * invisible to the coverage driver. Watch patterns are the only way to
+ * track them.
+ *
+ * @internal
+ */
+final readonly class Laravel implements WatchDefault
+{
+    public function applicable(): bool
+    {
+        return class_exists(InstalledVersions::class)
+            && InstalledVersions::isInstalled('laravel/framework');
+    }
+
+    public function defaults(string $projectRoot, string $testPath): array
+    {
+        $featurePath = is_dir($projectRoot.DIRECTORY_SEPARATOR.$testPath.'/Feature')
+            ? $testPath.'/Feature'
+            : $testPath;
+
+        return [
+            // Config — loaded during app boot (setUp), invisible to coverage.
+            // Affects both Feature and Unit: Pest.php commonly binds fakes
+            // and seeds DB based on config values.
+            'config/*.php' => [$testPath],
+            'config/**/*.php' => [$testPath],
+
+            // Routes — loaded during boot. HTTP/Feature tests depend on them.
+            'routes/*.php' => [$featurePath],
+            'routes/**/*.php' => [$featurePath],
+
+            // Service providers / bootstrap — loaded during boot, affect
+            // bindings, middleware, event listeners, scheduled tasks.
+            'bootstrap/app.php' => [$testPath],
+            'bootstrap/providers.php' => [$testPath],
+
+            // Migrations — run via RefreshDatabase/FastRefreshDatabase in
+            // setUp. Schema changes can break any test that touches DB.
+            'database/migrations/**/*.php' => [$testPath],
+
+            // Seeders — often run globally via Pest.php beforeEach.
+            'database/seeders/**/*.php' => [$testPath],
+
+            // Factories — loaded lazily but still PHP that coverage may miss
+            // if the factory file was already autoloaded before Prepared.
+            'database/factories/**/*.php' => [$testPath],
+
+            // Blade templates — compiled to cache, source file not executed.
+            'resources/views/**/*.blade.php' => [$featurePath],
+            // Email templates are nested under views/email or views/emails
+            // by convention and power mailable tests that render markup.
+            'resources/views/email/**/*.blade.php' => [$featurePath],
+            'resources/views/emails/**/*.blade.php' => [$featurePath],
+
+            // Translations — JSON translations read via file_get_contents,
+            // PHP translations loaded via include (but during boot).
+            'lang/**/*.php' => [$featurePath],
+            'lang/**/*.json' => [$featurePath],
+            'resources/lang/**/*.php' => [$featurePath],
+            'resources/lang/**/*.json' => [$featurePath],
+
+            // Build tool config — affects compiled assets consumed by
+            // browser and Inertia tests.
+            'vite.config.js' => [$featurePath],
+            'vite.config.ts' => [$featurePath],
+            'webpack.mix.js' => [$featurePath],
+            'tailwind.config.js' => [$featurePath],
+            'tailwind.config.ts' => [$featurePath],
+            'postcss.config.js' => [$featurePath],
+        ];
+    }
+}

src/Plugins/Tia/WatchDefaults/Livewire.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia\WatchDefaults;
+
+use Composer\InstalledVersions;
+
+/**
+ * Watch patterns for projects using Livewire.
+ *
+ * Livewire components pair a PHP class with a Blade view. A view change can
+ * break rendering or assertions in feature / browser tests even though the
+ * PHP side is untouched.
+ *
+ * @internal
+ */
+final readonly class Livewire implements WatchDefault
+{
+    public function applicable(): bool
+    {
+        return class_exists(InstalledVersions::class)
+            && InstalledVersions::isInstalled('livewire/livewire');
+    }
+
+    public function defaults(string $projectRoot, string $testPath): array
+    {
+        return [
+            // Livewire views live alongside Blade views or in a dedicated dir.
+            'resources/views/livewire/**/*.blade.php' => [$testPath],
+            'resources/views/components/**/*.blade.php' => [$testPath],
+            // Volt's second default mount — single-file components used as
+            // full-page routes. Missing this means editing a Volt page
+            // doesn't re-run its tests.
+            'resources/views/pages/**/*.blade.php' => [$testPath],
+
+            // Livewire JS interop / Alpine plugins.
+            'resources/js/**/*.js' => [$testPath],
+            'resources/js/**/*.ts' => [$testPath],
+        ];
+    }
+}

src/Plugins/Tia/WatchDefaults/Php.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia\WatchDefaults;
+
+/**
+ * Baseline watch patterns for any PHP project.
+ *
+ * @internal
+ */
+final readonly class Php implements WatchDefault
+{
+    public function applicable(): bool
+    {
+        return true;
+    }
+
+    public function defaults(string $projectRoot, string $testPath): array
+    {
+        // NOTE: composer.json / composer.lock changes are caught by the
+        // fingerprint (which hashes composer.lock). PHP files are tracked by
+        // the coverage driver. Only non-PHP, non-fingerprinted files that
+        // can silently alter test behaviour belong here.
+
+        return [
+            // Environment files — can change DB drivers, feature flags,
+            // queue connections, etc. Not PHP, not fingerprinted. Covers
+            // the local-override variants (`.env.local`, `.env.testing.local`)
+            // that both Laravel and Symfony recommend for machine-specific
+            // config.
+            '.env' => [$testPath],
+            '.env.testing' => [$testPath],
+            '.env.local' => [$testPath],
+            '.env.*.local' => [$testPath],
+
+            // Docker / CI — can affect integration test infrastructure.
+            'docker-compose.yml' => [$testPath],
+            'docker-compose.yaml' => [$testPath],
+
+            // PHPUnit / Pest config (XML) — phpunit.xml IS fingerprinted, but
+            // phpunit.xml.dist and other XML overrides are not individually
+            // tracked by the coverage driver.
+            'phpunit.xml.dist' => [$testPath],
+
+            // Test fixtures — JSON, CSV, XML, TXT data files consumed by
+            // assertions. A fixture change can flip a test result.
+            $testPath.'/Fixtures/**/*.json' => [$testPath],
+            $testPath.'/Fixtures/**/*.csv' => [$testPath],
+            $testPath.'/Fixtures/**/*.xml' => [$testPath],
+            $testPath.'/Fixtures/**/*.txt' => [$testPath],
+
+            // Pest snapshots — external edits to snapshot files invalidate
+            // snapshot assertions.
+            $testPath.'/.pest/snapshots/**/*.snap' => [$testPath],
+        ];
+    }
+}

src/Plugins/Tia/WatchDefaults/Symfony.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia\WatchDefaults;
+
+use Composer\InstalledVersions;
+
+/**
+ * Watch patterns for Symfony projects.
+ *
+ * @internal
+ */
+final readonly class Symfony implements WatchDefault
+{
+    public function applicable(): bool
+    {
+        return class_exists(InstalledVersions::class)
+            && InstalledVersions::isInstalled('symfony/framework-bundle');
+    }
+
+    public function defaults(string $projectRoot, string $testPath): array
+    {
+        // Symfony boots the kernel in setUp() (before the coverage window).
+        // PHP config, routes, kernel, and migrations are loaded during boot
+        // and invisible to the coverage driver. Same reasoning as Laravel.
+
+        return [
+            // Config — YAML, XML, and PHP. All loaded during kernel boot.
+            'config/*.yaml' => [$testPath],
+            'config/*.yml' => [$testPath],
+            'config/*.php' => [$testPath],
+            'config/*.xml' => [$testPath],
+            'config/**/*.yaml' => [$testPath],
+            'config/**/*.yml' => [$testPath],
+            'config/**/*.php' => [$testPath],
+            'config/**/*.xml' => [$testPath],
+
+            // Routes — loaded during boot.
+            'config/routes/*.yaml' => [$testPath],
+            'config/routes/*.php' => [$testPath],
+            'config/routes/*.xml' => [$testPath],
+            'config/routes/**/*.yaml' => [$testPath],
+
+            // Kernel / bootstrap — loaded during boot.
+            'src/Kernel.php' => [$testPath],
+
+            // Migrations — run during setUp (before coverage window).
+            // DoctrineMigrationsBundle's default is `migrations/` at the
+            // project root; many Symfony projects relocate to
+            // `src/Migrations/` — both covered.
+            'migrations/**/*.php' => [$testPath],
+            'src/Migrations/**/*.php' => [$testPath],
+
+            // Twig templates — compiled, source not PHP-executed.
+            'templates/**/*.html.twig' => [$testPath],
+            'templates/**/*.twig' => [$testPath],
+
+            // Translations (YAML / XLF / XLIFF).
+            'translations/**/*.yaml' => [$testPath],
+            'translations/**/*.yml' => [$testPath],
+            'translations/**/*.xlf' => [$testPath],
+            'translations/**/*.xliff' => [$testPath],
+
+            // Doctrine XML/YAML mappings.
+            'config/doctrine/**/*.xml' => [$testPath],
+            'config/doctrine/**/*.yaml' => [$testPath],
+
+            // Webpack Encore / asset-mapper config + frontend sources.
+            'webpack.config.js' => [$testPath],
+            'importmap.php' => [$testPath],
+            'assets/**/*.js' => [$testPath],
+            'assets/**/*.ts' => [$testPath],
+            'assets/**/*.vue' => [$testPath],
+            'assets/**/*.css' => [$testPath],
+            'assets/**/*.scss' => [$testPath],
+        ];
+    }
+}

src/Plugins/Tia/WatchDefaults/WatchDefault.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia\WatchDefaults;
+
+/**
+ * A set of file-watch patterns that apply when a particular framework,
+ * library or project layout is detected.
+ *
+ * Each implementation probes for the presence of the tool it covers
+ * (`applicable`) and returns glob → test-directory mappings (`defaults`)
+ * that are merged into `WatchPatterns`.
+ *
+ * @internal
+ */
+interface WatchDefault
+{
+    /**
+     * Whether this default set applies to the current project.
+     */
+    public function applicable(): bool;
+
+    /**
+     * @return array<string, array<int, string>> glob → list of project-relative test dirs
+     */
+    public function defaults(string $projectRoot, string $testPath): array;
+}

src/Plugins/Tia/WatchPatterns.php

@@ -0,0 +1,188 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Plugins\Tia;
+
+use Pest\Plugins\Tia\WatchDefaults\WatchDefault;
+use Pest\TestSuite;
+
+/**
+ * Maps non-PHP file globs to the test directories they should invalidate.
+ *
+ * Coverage drivers only see `.php` files. Frontend assets, config files,
+ * Blade templates, routes and environment files are invisible to the graph.
+ * Watch patterns bridge the gap: when a changed file matches a glob, every
+ * test under the associated directory is marked as affected.
+ *
+ * Defaults are assembled dynamically from the `WatchDefaults/` registry —
+ * each implementation probes the current project and contributes patterns
+ * when applicable. Users extend via `pest()->tia()->watch(…)`.
+ *
+ * @internal
+ */
+final class WatchPatterns
+{
+    /**
+     * All known default providers, in evaluation order.
+     *
+     * @var array<int, class-string<WatchDefault>>
+     */
+    private const array DEFAULTS = [
+        WatchDefaults\Php::class,
+        WatchDefaults\Laravel::class,
+        WatchDefaults\Symfony::class,
+        WatchDefaults\Livewire::class,
+        WatchDefaults\Inertia::class,
+        WatchDefaults\Browser::class,
+    ];
+
+    /**
+     * @var array<string, array<int, string>> glob → list of project-relative test dirs
+     */
+    private array $patterns = [];
+
+    /**
+     * Probes every registered `WatchDefault` and merges the patterns of
+     * those that apply. Called once during Tia plugin boot, after BootFiles
+     * has loaded `tests/Pest.php` (so user-added `pest()->tia()->watch()`
+     * calls are already in `$this->patterns`).
+     */
+    public function useDefaults(string $projectRoot): void
+    {
+        $testPath = TestSuite::getInstance()->testPath;
+
+        foreach (self::DEFAULTS as $class) {
+            $default = new $class;
+
+            if (! $default->applicable()) {
+                continue;
+            }
+
+            foreach ($default->defaults($projectRoot, $testPath) as $glob => $dirs) {
+                $this->patterns[$glob] = array_values(array_unique(
+                    array_merge($this->patterns[$glob] ?? [], $dirs),
+                ));
+            }
+        }
+    }
+
+    /**
+     * Adds user-defined patterns. Merges with existing entries so a single
+     * glob can map to multiple directories.
+     *
+     * @param  array<string, string>  $patterns  glob → project-relative test dir
+     */
+    public function add(array $patterns): void
+    {
+        foreach ($patterns as $glob => $dir) {
+            $this->patterns[$glob] = array_values(array_unique(
+                array_merge($this->patterns[$glob] ?? [], [$dir]),
+            ));
+        }
+    }
+
+    /**
+     * Returns all test directories whose watch patterns match at least one of
+     * the given changed files.
+     *
+     * @param  string  $projectRoot  Absolute path.
+     * @param  array<int, string>  $changedFiles  Project-relative paths.
+     * @return array<int, string> Project-relative test directories.
+     */
+    public function matchedDirectories(string $projectRoot, array $changedFiles): array
+    {
+        if ($this->patterns === []) {
+            return [];
+        }
+
+        $matched = [];
+
+        foreach ($changedFiles as $file) {
+            foreach ($this->patterns as $glob => $dirs) {
+                if ($this->globMatches($glob, $file)) {
+                    foreach ($dirs as $dir) {
+                        $matched[$dir] = true;
+                    }
+                }
+            }
+        }
+
+        return array_keys($matched);
+    }
+
+    /**
+     * Given the affected directories, returns every test file in the graph
+     * that lives under one of those directories.
+     *
+     * @param  array<int, string>  $directories  Project-relative dirs.
+     * @param  array<int, string>  $allTestFiles  Project-relative test files from graph.
+     * @return array<int, string>
+     */
+    public function testsUnderDirectories(array $directories, array $allTestFiles): array
+    {
+        if ($directories === []) {
+            return [];
+        }
+
+        $affected = [];
+
+        foreach ($allTestFiles as $testFile) {
+            foreach ($directories as $dir) {
+                $prefix = rtrim($dir, '/').'/';
+
+                if (str_starts_with($testFile, $prefix)) {
+                    $affected[] = $testFile;
+
+                    break;
+                }
+            }
+        }
+
+        return $affected;
+    }
+
+    public function reset(): void
+    {
+        $this->patterns = [];
+    }
+
+    /**
+     * Matches a project-relative file against a glob pattern.
+     *
+     * Supports `*` (single segment), `**` (any depth) and `?`.
+     */
+    private function globMatches(string $pattern, string $file): bool
+    {
+        $pattern = str_replace('\\', '/', $pattern);
+        $file = str_replace('\\', '/', $file);
+
+        $regex = '';
+        $len = strlen($pattern);
+        $i = 0;
+
+        while ($i < $len) {
+            $c = $pattern[$i];
+
+            if ($c === '*' && isset($pattern[$i + 1]) && $pattern[$i + 1] === '*') {
+                $regex .= '.*';
+                $i += 2;
+
+                if (isset($pattern[$i]) && $pattern[$i] === '/') {
+                    $i++;
+                }
+            } elseif ($c === '*') {
+                $regex .= '[^/]*';
+                $i++;
+            } elseif ($c === '?') {
+                $regex .= '[^/]';
+                $i++;
+            } else {
+                $regex .= preg_quote($c, '#');
+                $i++;
+            }
+        }
+
+        return (bool) preg_match('#^'.$regex.'$#', $file);
+    }
+}

src/Repositories/SnapshotRepository.php

@@ -59,8 +59,10 @@ final class SnapshotRepository
     {
         $snapshotFilename = $this->getSnapshotFilename();
 
-        if (! file_exists(dirname($snapshotFilename))) {
+        $directory = dirname($snapshotFilename);
-            mkdir(dirname($snapshotFilename), 0755, true);
+
+        if (! is_dir($directory)) {
+            @mkdir($directory, 0755, true);
         }
 
         file_put_contents($snapshotFilename, $snapshot);

src/Subscribers/EnsureShardTimingFinished.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use PHPUnit\Event\TestSuite\Finished;
+use PHPUnit\Event\TestSuite\FinishedSubscriber;
+
+/**
+ * @internal
+ */
+final class EnsureShardTimingFinished implements FinishedSubscriber
+{
+    /**
+     * Runs the subscriber.
+     */
+    public function notify(Finished $event): void
+    {
+        EnsureShardTimingsAreCollected::finished($event);
+    }
+}

src/Subscribers/EnsureShardTimingStarted.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use PHPUnit\Event\TestSuite\Started;
+use PHPUnit\Event\TestSuite\StartedSubscriber;
+
+/**
+ * @internal
+ */
+final class EnsureShardTimingStarted implements StartedSubscriber
+{
+    /**
+     * Runs the subscriber.
+     */
+    public function notify(Started $event): void
+    {
+        EnsureShardTimingsAreCollected::started($event);
+    }
+}

src/Subscribers/EnsureShardTimingsAreCollected.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use PHPUnit\Event\Telemetry\HRTime;
+use PHPUnit\Event\TestSuite\Finished;
+use PHPUnit\Event\TestSuite\Started;
+
+/**
+ * @internal
+ */
+final class EnsureShardTimingsAreCollected
+{
+    /**
+     * The start times for each test class.
+     *
+     * @var array<string, HRTime>
+     */
+    private static array $startTimes = [];
+
+    /**
+     * The collected timings for each test class.
+     *
+     * @var array<string, float>
+     */
+    private static array $timings = [];
+
+    /**
+     * Records the start time for a test suite.
+     */
+    public static function started(Started $event): void
+    {
+        if (! $event->testSuite()->isForTestClass()) {
+            return;
+        }
+
+        $name = preg_replace('/^P\\\\/', '', $event->testSuite()->name());
+
+        if (is_string($name)) {
+            self::$startTimes[$name] = $event->telemetryInfo()->time();
+        }
+    }
+
+    /**
+     * Records the duration for a test suite.
+     */
+    public static function finished(Finished $event): void
+    {
+        if (! $event->testSuite()->isForTestClass()) {
+            return;
+        }
+
+        $name = preg_replace('/^P\\\\/', '', $event->testSuite()->name());
+
+        if (! is_string($name) || ! isset(self::$startTimes[$name])) {
+            return;
+        }
+
+        $duration = $event->telemetryInfo()->time()->duration(self::$startTimes[$name]);
+
+        self::$timings[$name] = round($duration->asFloat(), 4);
+    }
+
+    /**
+     * Returns the collected timings.
+     *
+     * @return array<string, float>
+     */
+    public static function timings(): array
+    {
+        return self::$timings;
+    }
+}

src/Subscribers/EnsureTiaAssertionsAreRecordedOnFinished.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\ResultCollector;
+use PHPUnit\Event\Code\TestMethod;
+use PHPUnit\Event\Test\Finished;
+use PHPUnit\Event\Test\FinishedSubscriber;
+
+/**
+ * Fires last for each test, after the outcome subscribers. Records the exact
+ * assertion count so replay can emit the same `addToAssertionCount()` instead
+ * of a hardcoded value.
+ *
+ * @internal
+ */
+final readonly class EnsureTiaAssertionsAreRecordedOnFinished implements FinishedSubscriber
+{
+    public function __construct(private ResultCollector $collector) {}
+
+    public function notify(Finished $event): void
+    {
+        $test = $event->test();
+
+        if ($test instanceof TestMethod) {
+            $this->collector->recordAssertions(
+                $test->className().'::'.$test->methodName(),
+                $event->numberOfAssertionsPerformed(),
+            );
+        }
+
+        // Close the "currently recording" window on Finished so the next
+        // test's events don't get mis-attributed. Keeping the pointer open
+        // through the outcome subscribers is what lets a late-firing
+        // `ConsideredRisky` overwrite an earlier `Passed`.
+        $this->collector->finishTest();
+    }
+}

src/Subscribers/EnsureTiaCoverageIsFlushed.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\Recorder;
+use PHPUnit\Event\Test\Finished;
+use PHPUnit\Event\Test\FinishedSubscriber;
+
+/**
+ * Stops PCOV collection after each test and merges the covered files into the
+ * TIA recorder's aggregate map. No-op unless the recorder is active.
+ *
+ * @internal
+ */
+final readonly class EnsureTiaCoverageIsFlushed implements FinishedSubscriber
+{
+    public function __construct(private Recorder $recorder) {}
+
+    public function notify(Finished $event): void
+    {
+        $this->recorder->endTest();
+    }
+}

src/Subscribers/EnsureTiaCoverageIsRecorded.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\Recorder;
+use PHPUnit\Event\Code\TestMethod;
+use PHPUnit\Event\Test\Prepared;
+use PHPUnit\Event\Test\PreparedSubscriber;
+
+/**
+ * Starts PCOV collection before each test. No-op unless the TIA recorder was
+ * activated by the `--tia` plugin.
+ *
+ * @internal
+ */
+final readonly class EnsureTiaCoverageIsRecorded implements PreparedSubscriber
+{
+    public function __construct(private Recorder $recorder) {}
+
+    public function notify(Prepared $event): void
+    {
+        if (! $this->recorder->isActive()) {
+            return;
+        }
+
+        $test = $event->test();
+
+        if (! $test instanceof TestMethod) {
+            return;
+        }
+
+        $this->recorder->beginTest($test->className(), $test->methodName(), $test->file());
+    }
+}

src/Subscribers/EnsureTiaResultIsRecordedOnErrored.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\ResultCollector;
+use PHPUnit\Event\Test\Errored;
+use PHPUnit\Event\Test\ErroredSubscriber;
+
+/**
+ * @internal
+ */
+final readonly class EnsureTiaResultIsRecordedOnErrored implements ErroredSubscriber
+{
+    public function __construct(private ResultCollector $collector) {}
+
+    public function notify(Errored $event): void
+    {
+        $this->collector->testErrored($event->throwable()->message());
+    }
+}

src/Subscribers/EnsureTiaResultIsRecordedOnFailed.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\ResultCollector;
+use PHPUnit\Event\Test\Failed;
+use PHPUnit\Event\Test\FailedSubscriber;
+
+/**
+ * @internal
+ */
+final readonly class EnsureTiaResultIsRecordedOnFailed implements FailedSubscriber
+{
+    public function __construct(private ResultCollector $collector) {}
+
+    public function notify(Failed $event): void
+    {
+        $this->collector->testFailed($event->throwable()->message());
+    }
+}

src/Subscribers/EnsureTiaResultIsRecordedOnIncomplete.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\ResultCollector;
+use PHPUnit\Event\Test\MarkedIncomplete;
+use PHPUnit\Event\Test\MarkedIncompleteSubscriber;
+
+/**
+ * @internal
+ */
+final readonly class EnsureTiaResultIsRecordedOnIncomplete implements MarkedIncompleteSubscriber
+{
+    public function __construct(private ResultCollector $collector) {}
+
+    public function notify(MarkedIncomplete $event): void
+    {
+        $this->collector->testIncomplete($event->throwable()->message());
+    }
+}

src/Subscribers/EnsureTiaResultIsRecordedOnPassed.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\ResultCollector;
+use PHPUnit\Event\Test\Passed;
+use PHPUnit\Event\Test\PassedSubscriber;
+
+/**
+ * @internal
+ */
+final readonly class EnsureTiaResultIsRecordedOnPassed implements PassedSubscriber
+{
+    public function __construct(private ResultCollector $collector) {}
+
+    public function notify(Passed $event): void
+    {
+        $this->collector->testPassed();
+    }
+}

src/Subscribers/EnsureTiaResultIsRecordedOnRisky.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\ResultCollector;
+use PHPUnit\Event\Test\ConsideredRisky;
+use PHPUnit\Event\Test\ConsideredRiskySubscriber;
+
+/**
+ * @internal
+ */
+final readonly class EnsureTiaResultIsRecordedOnRisky implements ConsideredRiskySubscriber
+{
+    public function __construct(private ResultCollector $collector) {}
+
+    public function notify(ConsideredRisky $event): void
+    {
+        $this->collector->testRisky($event->message());
+    }
+}

src/Subscribers/EnsureTiaResultIsRecordedOnSkipped.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\ResultCollector;
+use PHPUnit\Event\Test\Skipped;
+use PHPUnit\Event\Test\SkippedSubscriber;
+
+/**
+ * @internal
+ */
+final readonly class EnsureTiaResultIsRecordedOnSkipped implements SkippedSubscriber
+{
+    public function __construct(private ResultCollector $collector) {}
+
+    public function notify(Skipped $event): void
+    {
+        $this->collector->testSkipped($event->message());
+    }
+}

src/Subscribers/EnsureTiaResultsAreCollected.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Subscribers;
+
+use Pest\Plugins\Tia\ResultCollector;
+use PHPUnit\Event\Code\TestMethod;
+use PHPUnit\Event\Test\Prepared;
+use PHPUnit\Event\Test\PreparedSubscriber;
+
+/**
+ * Starts a per-test recording window on Prepared. Sibling subscribers
+ * (`EnsureTia*`) close it with the outcome and the assertion count so the
+ * graph can persist everything needed for faithful replay.
+ *
+ * Why one subscriber per event: PHPUnit's `TypeMap::map()` picks only the
+ * first subscriber interface it finds on a class, so one class cannot fan
+ * out to multiple events — each event needs its own subscriber class.
+ *
+ * @internal
+ */
+final readonly class EnsureTiaResultsAreCollected implements PreparedSubscriber
+{
+    public function __construct(private ResultCollector $collector) {}
+
+    public function notify(Prepared $event): void
+    {
+        $test = $event->test();
+
+        if ($test instanceof TestMethod) {
+            $this->collector->testPrepared($test->className().'::'.$test->methodName());
+        }
+    }
+}

src/Support/Coverage.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Pest\Support;
 
 use Pest\Exceptions\ShouldNotHappen;
+use Pest\Plugins\Tia\CoverageMerger;
 use SebastianBergmann\CodeCoverage\CodeCoverage;
 use SebastianBergmann\CodeCoverage\Node\Directory;
 use SebastianBergmann\CodeCoverage\Node\File;
@@ -88,6 +89,12 @@ final class Coverage
             throw ShouldNotHappen::fromMessage(sprintf('Coverage not found in path: %s.', $reportPath));
         }
 
+        // If TIA's marker is present, this run executed only the affected
+        // tests. Merge their fresh coverage slice into the cached full-run
+        // snapshot (stored by the previous `--tia --coverage` pass) so the
+        // report reflects the entire suite, not just what re-ran.
+        CoverageMerger::applyIfMarked($reportPath);
+
         /** @var CodeCoverage $codeCoverage */
         $codeCoverage = require $reportPath;
         unlink($reportPath);

tests/.pest/snapshots/Features/Expect/toMatchSnapshot/failures.snap

@@ -1,7 +0,0 @@
-    <div class="container">
-        <div class="row">
-            <div class="col-md-12">
-                <h1>Snapshot</h1>
-            </div>
-        </div>
-    </div>

tests/.pest/snapshots/Features/Expect/toMatchSnapshot/failures_with_custom_message.snap

@@ -1,7 +0,0 @@
-    <div class="container">
-        <div class="row">
-            <div class="col-md-12">
-                <h1>Snapshot</h1>
-            </div>
-        </div>
-    </div>

tests/.pest/snapshots/Visual/Help/visual_snapshot_of_help_command_output.snap

@@ -1,5 +1,5 @@
 
-  Pest Testing Framework 4.4.4.  
+  Pest Testing Framework 4.6.3.  
 
   USAGE: pest <file> [options]  
 
@@ -49,6 +49,7 @@
   EXECUTION OPTIONS:
   --parallel ........................................... Run tests in parallel  
   --update-snapshots  Update snapshots for tests using the "toMatchSnapshot" expectation  
+  --update-shards  Update shards.json with test timing data for time-balanced sharding  
   --globals-backup ................. Backup and restore $GLOBALS for each test  
   --static-backup ......... Backup and restore static properties for each test  
   --strict-coverage ................... Be strict about code coverage metadata  
@@ -90,7 +91,11 @@
   --cache-result ............................ Write test results to cache file  
   --do-not-cache-result .............. Do not write test results to cache file  
   --order-by [order]  Run tests in order: default|defects|depends|duration|no-depends|random|reverse|size  
+  --resolve-dependencies ...................... Alias for "--order-by depends"  
+  --ignore-dependencies .................... Alias for "--order-by no-depends"  
+  --random-order ............................... Alias for "--order-by random"  
   --random-order-seed [N]  Use the specified random seed when running tests in random order  
+  --reverse-order ............................. Alias for "--order-by reverse"  
 
   REPORTING OPTIONS:
   --colors=[flag] ......... Use colors in output ("never", "auto" or "always")  

tests/.pest/snapshots/Visual/Version/visual_snapshot_of_help_command_output.snap

@@ -1,3 +1,3 @@
 
-  Pest Testing Framework 4.4.4.  
+  Pest Testing Framework 4.6.3.  
 

tests/.snapshots/success.txt

@@ -1037,8 +1037,6 @@
   ✓ pass with toArray
   ✓ pass with array
   ✓ pass with toSnapshot
-  ✓ failures
-  ✓ failures with custom message
   ✓ not failures
   ✓ multiple snapshot expectations
   ✓ multiple snapshot expectations with datasets with (1)
@@ -1903,4 +1901,4 @@
   ✓ pass with dataset with ('my-datas-set-value')
   ✓ within describe → pass with dataset with ('my-datas-set-value')
 
-  Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 40 todos, 35 skipped, 1296 passed (2977 assertions)
+  Tests:    2 deprecated, 4 warnings, 5 incomplete, 2 notices, 40 todos, 35 skipped, 1294 passed (2971 assertions)

tests/Arch.php

@@ -7,6 +7,9 @@ arch()->preset()->php()->ignoring([
     'debug_backtrace',
     'var_export',
     'xdebug_info',
+    'xdebug_start_code_coverage',
+    'xdebug_stop_code_coverage',
+    'xdebug_get_code_coverage',
 ]);
 
 arch()->preset()->strict()->ignoring([
@@ -17,7 +20,9 @@ arch()->preset()->security()->ignoring([
     'eval',
     'str_shuffle',
     'exec',
+    'md5',
     'unserialize',
+    'uniqid',
     'extract',
     'assert',
 ]);

tests/Features/Expect/toMatchSnapshot.php

@@ -134,18 +134,6 @@ test('pass with `toSnapshot`', function () {
     expect($object)->toMatchSnapshot();
 });
 
-test('failures', function () {
-    TestSuite::getInstance()->snapshots->save($this->snapshotable);
-
-    expect('contain that does not match snapshot')->toMatchSnapshot();
-})->throws(ExpectationFailedException::class, 'Failed asserting that two strings are identical.');
-
-test('failures with custom message', function () {
-    TestSuite::getInstance()->snapshots->save($this->snapshotable);
-
-    expect('contain that does not match snapshot')->toMatchSnapshot('oh no');
-})->throws(ExpectationFailedException::class, 'oh no');
-
 test('not failures', function () {
     TestSuite::getInstance()->snapshots->save($this->snapshotable);
 

tests/Pest.php

@@ -86,5 +86,12 @@ dataset('dataset_in_pest_file', ['A', 'B']);
 
 function removeAnsiEscapeSequences(string $input): ?string
 {
-    return preg_replace('#\\x1b[[][^A-Za-z]*[A-Za-z]#', '', $input);
+    return preg_replace(
+        [
+            '#\\x1b[[][^A-Za-z]*[A-Za-z]#',       // CSI (colors, cursor, etc.)
+            '#\\x1b\\]8;[^\\x1b\\x07]*(?:\\x1b\\\\|\\x07)#', // OSC 8 hyperlinks
+        ],
+        '',
+        $input,
+    );
 }

tests/Visual/Parallel.php

@@ -23,13 +23,13 @@ test('parallel', function () use ($run) {
         $file = file_get_contents(__FILE__);
         $file = preg_replace(
             '/\$expected = \'.*?\';/',
-            "\$expected = '2 deprecated, 4 warnings, 5 incomplete, 3 notices, 40 todos, 27 skipped, 1280 passed (2926 assertions)';",
+            "\$expected = '2 deprecated, 4 warnings, 5 incomplete, 3 notices, 40 todos, 27 skipped, 1278 passed (2920 assertions)';",
             $file,
         );
         file_put_contents(__FILE__, $file);
     }
 
-    $expected = '2 deprecated, 4 warnings, 5 incomplete, 3 notices, 40 todos, 27 skipped, 1280 passed (2926 assertions)';
+    $expected = '2 deprecated, 4 warnings, 5 incomplete, 3 notices, 40 todos, 27 skipped, 1278 passed (2920 assertions)';
 
     expect($output)
         ->toContain("Tests:    {$expected}")

tests/Visual/Success.php

@@ -21,8 +21,10 @@ test('visual snapshot of test suite on success', function () {
 
         return preg_replace([
             '#\\x1b[[][^A-Za-z]*[A-Za-z]#',
+            '#\\x1b\\]8;[^\\x1b\\x07]*(?:\\x1b\\\\|\\x07)#',
             '/(Tests\\\PHPUnit\\\CustomAffixes\\\InvalidTestName)([A-Za-z0-9]*)/',
         ], [
+            '',
             '',
             '$1',
         ], $process->getOutput());