Weave Code
Phpunit Snapshot Assertions Laravel Package
spatie/phpunit-snapshot-assertions
Add snapshot testing to PHPUnit. Save expected output (JSON, arrays, strings, etc.) on first run and automatically compare on later runs to catch regressions with minimal assertions. Includes handy traits and snapshot update workflow for tests.
A way to test without writing actual test cases
Frequently asked questions about Phpunit Snapshot Assertions
- How do I add snapshot testing to a Laravel project using PHPUnit?
- Install the package via Composer with `composer require --dev spatie/phpunit-snapshot-assertions`, then use the `MatchesSnapshots` trait in your test class. Run your tests once to generate snapshots, and subsequent runs will compare outputs automatically. No Laravel-specific configuration is needed.
- Can I use this package with Pest instead of PHPUnit?
- Yes, the package works seamlessly with Pest. Simply include the `MatchesSnapshots` trait in your test class, and use methods like `assertMatchesJsonSnapshot()` just as you would in PHPUnit. Pest’s syntax compatibility ensures a smooth transition.
- What Laravel versions does this package support?
- The package is framework-agnostic and works with any Laravel version that supports PHPUnit 9.x or later. It’s designed to integrate with Laravel’s testing stack, including API testing, view rendering, and command output validation, without version-specific dependencies.
- How do I handle snapshot updates in CI vs. local development?
- Use environment variables to control snapshot behavior. Set `UPDATE_SNAPSHOTS=true` locally to update snapshots during development, and disable snapshot creation in CI with `CREATE_SNAPSHOTS=false`. This ensures CI fails only on regressions, not missing snapshots.
- Will snapshot testing slow down my Laravel test suite?
- Snapshot comparisons are lightweight, but large outputs (e.g., full API responses) may impact performance. For critical tests, use `assertMatchesFileHashSnapshot()` to optimize comparisons. Benchmark with `phpunit --stop-on-failure` to assess the impact in your specific Laravel project.
- How do I test Laravel API responses with snapshot assertions?
- Use `assertMatchesJsonSnapshot($response->json())` in your test class. For partial responses, extract the relevant data first (e.g., `$response->json()['data']`). This avoids flakiness from non-deterministic fields like timestamps or tokens.
- Can I customize snapshot storage or naming conventions?
- Snapshots are stored in the `__snapshots__` directory by default, with filenames like `TestClass__testMethod__1.snapshot`. You can override the storage path via the `SnapshotPath` trait or configure custom naming in the `SnapshotTestCase` setup.
- What’s the best way to avoid false positives in snapshot tests?
- Avoid snapshotting entire API responses or dynamic data (e.g., UUIDs, timestamps). Use named snapshots for critical outputs (e.g., `assertMatchesJsonSnapshot($response, 'user-profile')`) and combine with explicit assertions for edge cases. Exclude non-deterministic fields using custom drivers or JSON normalization.
- How do I clean up old snapshots in a Laravel project?
- Since snapshots are text files, use Git to track changes or add a Composer script to prune old snapshots. For example, run `git clean -f __snapshots__` in a post-test hook or use `php artisan snapshot:prune` if you extend the package with custom commands.
- Are there alternatives to this package for Laravel snapshot testing?
- For Laravel, alternatives include `laravel-shift/snapshot-testing` (built for Laravel’s testing helpers) or `mockery/mockery` for mock-based testing. However, Spatie’s package offers broader language support (JSON, HTML, XML) and tighter PHPUnit integration, making it ideal for Laravel projects requiring regression testing across multiple output formats.
Weaver
How can I help you explore Laravel packages today?