Phpunit Snapshot Assertions Laravel Package

Getting Started

Install via composer require --dev spatie/phpunit-snapshot-assertions, then use the Spatie\Snapshots\MatchesSnapshots trait in your test class. Start with simple string or JSON assertions:

public function test_rendered_output() {
    $this->assertMatchesJsonSnapshot(json_encode(['status' => 'ok']));
}

On first run, this creates a snapshot file (e.g., __snapshots__/TestName__test_rendered_output__1.json). Subsequent runs will pass if output matches; otherwise, they fail with a diff. Use phpunit -d --update-snapshots (or UPDATE_SNAPSHOTS=1) to refresh snapshots after intentional changes.

Implementation Patterns

• Use domain-specific assertions: Prefer assertMatchesJsonSnapshot(), assertMatchesHtmlSnapshot(), or assertMatchesXmlSnapshot() over generic assertMatchesSnapshot() for better formatting and semantic assertions.
• Name snapshots for reliability: Pass a third parameter (e.g., 'user-view') to avoid brittle auto-incrementing IDs, especially for tests with multiple snapshots or flaky auto-increment behavior.
• Integrate with Laravel:
  • Store snapshots in tests/__snapshots__ (default).
  • Use php artisan test --parallel with CREATE_SNAPSHOTS=false in CI to avoid write conflicts.
• File-based workflows: For binary files (e.g., PDFs, images), use assertMatchesFileSnapshot() to persist the actual file on failure for visual diffing.
• Custom drivers: Extend Driver interface to handle domain formats (e.g., YamlDriver, PDFTextDriver). Implement serialize(), extension(), and match() to control formatting and comparison logic.

Gotchas and Tips

• Line endings: In .gitattributes, mark snapshot directories as binary (e.g., tests/**/__snapshots__/** binary) to prevent Git from normalizing line endings on Windows/macOS.
• CI safety: Always run tests with CREATE_SNAPSHOTS=false in CI to fail fast if snapshots are missing or out of sync—do not allow snapshot creation in CI pipelines.
• Update carefully: Never run UPDATE_SNAPSHOTS=1 without code review; manually verify diffs to catch unintended regressions. Consider using phpunit --filter=test_.*named.* to update only specific snapshots.
• Debugging: Enable phpunit --debug to see exact file paths of snapshots; failed snapshots (e.g., for assertMatchesFileSnapshot()) are written side-by-side for manual inspection.
• Named vs. auto IDs: Auto IDs increment per test but reset when test order changes; named snapshots ('order-api-response') avoid this fragility but require manual naming discipline.
• Git workflow: Treat snapshot files like source code—stage/commit them as part of your PRs. Add .gitignore entries only for temp files (e.g., .tmp.png), never for snapshots themselves.
• Image snapshots: Require spatie/pixelmatch-php; use threshold tuning (e.g., 0.05 for strict, 0.2 for flaky UIs) and verify pixel-diff files are generated on failure.