Weave Code
Phpunit Snapshot Assertions Laravel Package
spatie/phpunit-snapshot-assertions
Snapshot testing for PHPUnit: assert values match stored snapshots for JSON, strings, arrays, and more. Snapshots are created automatically on first run and compared on subsequent runs.
spatie/phpunit-snapshot-assertions brings snapshot testing to PHPUnit, letting you verify complex output without hand-writing every expected value. On the first run it creates a snapshot; later runs compare against it and fail when output changes, making regressions easy to spot.
- JSON snapshots via
assertMatchesJsonSnapshot() - String, array, object, and file snapshots
- Automatic snapshot creation and comparison
- Clear diff output on failures
- Works in Laravel and non-Laravel PHP projects
Frequently asked questions about Phpunit Snapshot Assertions
- How do I install spatie/phpunit-snapshot-assertions in a Laravel project?
- Install it as a dev dependency with composer require --dev spatie/phpunit-snapshot-assertions. Then add the Spatie\Snapshots\MatchesSnapshots trait to the test case that needs it, or register it globally in your base Tests\TestCase. In Pest you can enable it with uses(MatchesSnapshots::class) in your Pest.php file. No service provider, config file, or migration is involved, so installation is complete after Composer finishes.
- Which snapshot assertions does the package provide?
- It ships nine assertion flavours: assertMatchesSnapshot for raw text, plus dedicated methods for JSON, HTML, XML, YAML, objects, whole files, file hashes, and images. Each is a one-line change to an existing test, so you can adopt them incrementally. You can also pass a named snapshot ID as a second argument, such as assertMatchesJsonSnapshot($json, 'order-json'), to avoid brittle auto-incremented snapshot names in refactor-heavy suites.
- Does it work with Pest and non-Laravel PHP projects?
- Yes. The package is framework-agnostic and only depends on PHPUnit, so it works in plain PHP packages, Laravel apps, and Pest suites alike. In Pest you apply the MatchesSnapshots trait through uses(), and in PHPUnit you add it to any test case class. The same convention can therefore span a monorepo containing both an application and shared libraries.
- How do I update snapshots after an intentional change?
- Run vendor/bin/update-snapshots, which is the supported wrapper shipped with the package. You can also set the UPDATE_SNAPSHOTS environment variable, which maps cleanly onto Composer scripts and CI configuration. Avoid relying on old phpunit -d --update-snapshots examples, because PHPUnit 12.5.12 and later emit warnings for those abused -d flags.
- Why does my snapshot test report incomplete instead of failing in CI?
- On a first run the package creates a missing snapshot and marks the test as incomplete rather than failed, which some CI setups treat as a pass. Set CREATE_SNAPSHOTS=false in every CI entry point, including php artisan test --parallel paths, so a missing baseline fails closed. This is the single most important configuration item when adopting the package.
- Which PHPUnit and Laravel versions are supported?
- The package targets PHPUnit rather than Laravel, so it is not tied to a specific Laravel release; any Laravel version running a supported PHPUnit and PHP combination will work. Because the package tracks PHPUnit internals, pin your PHPUnit major and check the package's Composer constraints before upgrading. Teams on older -d flag patterns will see noise or breakage on PHPUnit upgrades, so prefer the wrapper binary and environment variables.
- Should snapshot files be committed to version control?
- Yes. Snapshots are stored in __snapshots__ directories alongside your tests and must be committed so every environment compares against the same baseline. Treat an unreviewed snapshot update as a silently weakened test, and make sure a human reads snapshot diffs in pull requests. Without that discipline the suite can drift into rubber-stamped approvals.
- How do I stop snapshot tests from becoming flaky?
- Snapshot assertions are only as reliable as the serialisation they capture, so normalise non-deterministic output before asserting. Freeze time with Carbon::setTestNow, mask or fake UUIDs, format floats explicitly, and avoid locale-dependent strings in the tested code path. Doing this deliberately keeps diffs meaningful instead of producing constant noise.
- Does this package add any runtime overhead in production?
- No. It is a dev-only Composer dependency that adds a trait to PHPUnit test cases and has zero runtime footprint. It registers no service container bindings, publishes no config, and ships nothing in the application artifact because composer install --no-dev excludes it. It never touches the request lifecycle, queue workers, or deployment topology.
- What are the alternatives to snapshot testing in Laravel?
- The main alternative is writing explicit assertions on the values you care about, which stays precise but becomes verbose for large JSON or HTML payloads. Pest also offers snapshot-style helpers, and approval-testing libraries follow a similar workflow. Snapshot assertions are additive, so most teams keep explicit assertions for critical business rules and use snapshots for serialisation contracts, rendered mail, and generated files.
Weaver
How can I help you explore Laravel packages today?