Weave Code
Phpunit Snapshot Assertions Laravel Package
spatie/phpunit-snapshot-assertions
Add snapshot testing to PHPUnit. Assert strings, JSON, arrays, and objects against saved snapshots; first run writes snapshots, later runs compare and fail on regressions. Simple trait-based API (e.g., assertMatchesJsonSnapshot) for PHP and Laravel projects.
A way to test without writing actual test cases
Frequently asked questions about Phpunit Snapshot Assertions
- How do I install spatie/phpunit-snapshot-assertions in a Laravel project?
- Run `composer require --dev spatie/phpunit-snapshot-assertions` to install the package. No additional Laravel configuration is needed—just use the `MatchesSnapshots` trait in your test classes. Works seamlessly with Laravel’s PHPUnit or Pest testing frameworks.
- Can I use this package for testing Laravel API responses or JSON payloads?
- Yes, it’s perfect for API testing. Use `assertMatchesJsonSnapshot()` to snapshot JSON responses from routes, controllers, or Eloquent models. The first run creates a snapshot, and subsequent runs verify no regressions. Works with Laravel’s `Http::fake()` or real HTTP requests.
- Will this work with Pest PHP testing framework instead of PHPUnit?
- Absolutely. The package supports Pest natively. Use the `@snapshot` macro (e.g., `test('it matches snapshot')->snapshot($response->json())`) for concise syntax. All PHPUnit assertions also work in Pest tests.
- How do I handle dynamic data like timestamps or UUIDs in snapshots?
- Avoid including non-deterministic data in snapshots by preprocessing values before asserting. For example, replace `now()` with a placeholder or use custom drivers to normalize data. The package’s diff output highlights mismatches, making it easy to spot issues.
- What’s the best way to manage snapshot updates in CI/CD pipelines?
- Use environment variables to control snapshot behavior: `CREATE_SNAPSHOTS=false` in CI for strict validation, or `UPDATE_SNAPSHOTS=true` in dev to auto-update snapshots. For a hybrid approach, auto-update in a dev branch but require manual approval for critical paths.
- Can I snapshot Blade templates or HTML emails in Laravel?
- Yes, snapshot Blade-rendered HTML or email content using `assertMatchesSnapshot()`. For emails, combine with Laravel’s `Mail::fake()` to capture the rendered message. Note: Exclude non-deterministic elements (e.g., dynamic IDs) to avoid flaky tests.
- How do I exclude specific fields or paths from snapshots?
- Use the `ignore()` method in your assertions to exclude fields. For example, `assertMatchesJsonSnapshot($response->json())->ignore('meta.timestamp')` skips dynamic timestamps. You can also customize drivers to filter data before snapshotting.
- What Laravel versions and PHPUnit versions are supported?
- The package supports Laravel 8+ and PHP 8.0+. It requires PHPUnit 9.5+ or Pest 2+. Check the [GitHub repo](https://github.com/spatie/phpunit-snapshot-assertions) for the latest compatibility matrix, as minor updates may add support for newer Laravel releases.
- How do I run snapshot tests in parallel without race conditions?
- Disable snapshot creation in CI (`CREATE_SNAPSHOTS=false`) and update snapshots manually in development. If using parallel test workers, ensure only one worker updates snapshots at a time, or use a dedicated script like `artisan update:snapshots` for Laravel projects.
- Are there alternatives to this package for snapshot testing in Laravel?
- Yes, alternatives include `league/container-snapshot` (for service containers) or custom solutions using `assertJson()` with `assertEquals()`. However, Spatie’s package offers a dedicated, Laravel-friendly API with clear diffs, named snapshots, and built-in support for JSON, arrays, and strings—reducing boilerplate significantly.
Weaver
How can I help you explore Laravel packages today?