Open-Source Testing · spatie

phpunit-snapshot-assertions

phpunit-snapshot-assertions is a PHP testing library that enables snapshot testing—a technique where test outputs are captured once and compared automatically on subsequent runs. It integrates directly with PHPUnit and supports multiple output formats (JSON, XML, HTML, images, files) for regression detection.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/spatie/phpunit-snapshot-assertions

696

GitHub stars

Forks

PHP

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	spatie/phpunit-snapshot-assertions
Owner	spatie
Primary language	PHP
License	MIT — OSI-approved
Stars	696
Forks	74
Open issues	0
Latest release	5.4.0 (2026-04-29)
Last updated	2026-06-26
Source	https://github.com/spatie/phpunit-snapshot-assertions

What phpunit-snapshot-assertions is

A PHPUnit trait-based extension that provides assertion methods for snapshot-driven testing across various data types. Snapshots are persisted as files and compared using diff-based or hash-based strategies; developers trigger updates via an UPDATE_SNAPSHOTS environment variable or wrapper binary.

Quickstart

Get the phpunit-snapshot-assertions source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/spatie/phpunit-snapshot-assertions.git2cd phpunit-snapshot-assertions3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Regression Testing for Complex Data Structures

Ideal for detecting unexpected changes in JSON API responses, serialized objects, or structured output without maintaining brittle equality assertions.

Visual/Image Regression Testing

Supports pixel-level image comparison with configurable thresholds via spatie/pixelmatch-php, useful for screenshot or rendered output validation.

HTML & Generated Content Verification

Captures snapshots of rendered HTML, XML, or formatted output to catch layout, formatting, or content generation regressions early.

Implementation considerations

Snapshots are committed to version control; establish clear team guidelines on snapshot review and approval in pull requests to prevent accidental logic bugs masquerading as diffs.
Use named snapshot IDs (via the $id parameter) for clarity in multi-assertion tests; auto-incremented IDs become opaque as test suites grow.
Image snapshots require spatie/pixelmatch-php as an optional dependency; verify it is installed and the threshold parameter is tuned to your tolerance for pixel variance.
The UPDATE_SNAPSHOTS environment variable or wrapper binary must be used consistently; legacy `-d` flag syntax now produces warnings on PHPUnit 12.5.12+.
Plan snapshot directory structure early; by default, snapshots are generated alongside test files and can accumulate quickly in large suites.

When to avoid it — and what to weigh

Unstable or Frequently Changing Outputs — If tested values legitimately vary frequently (timestamps, random IDs, external API responses), snapshot tests will require constant updates and lose effectiveness.
Need for Explicit Assertion Logic — Snapshot testing is passive comparison; if you need conditional or parametric assertions (e.g., 'age must be > 18'), explicit test logic is more appropriate.
Large Binary Files or Performance-Sensitive Scenarios — While file snapshots are supported, persisting large artifacts for every test run can slow CI pipelines and bloat repositories.
Teams Unfamiliar with Snapshot Workflows — Developers must understand when to update snapshots vs. when a diff signals a real bug; miscommunication can lead to false passes or unnecessary churn.

License & commercial use

Licensed under the MIT License, a permissive open-source license that permits commercial use, modification, and distribution with minimal restrictions.

MIT license permits commercial use without additional licensing fees or permission. No evidence in the data of proprietary restrictions or commercial licensing requirements. Use in production is straightforward from a licensing perspective.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Snapshot files are plain text or binary blobs stored alongside tests; ensure snapshot directories are not publicly exposed in production deployments. No cryptographic or authentication mechanisms are built into the library; security relies on standard file system permissions and version control access control. Developers should review snapshot diffs carefully, as unintended output changes could slip past review if treated as acceptable diffs.

Alternatives to consider

Jest Snapshots (JavaScript/Node.js)

Industry-standard snapshot testing framework for JavaScript; more mature ecosystem and tooling, but not applicable to PHP projects.

PHPUnit Golden Master / Approval Testing

Manual approval-based testing using custom assertions; more explicit control but requires more boilerplate and lacks built-in comparison tools.

Pest Framework with Snapshot Plugin

Pest is a newer PHPUnit-based framework with integrated snapshot support; may be preferable if adopting Pest as your test runner, but phpunit-snapshot-assertions is framework-agnostic.

Software development agency

Build on phpunit-snapshot-assertions with DEV.co software developers

Snapshot testing cuts down on brittle assertions and boilerplate. Integrate phpunit-snapshot-assertions into your PHP test suite today—or let our team guide your testing strategy.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

swift-snapshot-testing jest-image-snapshot inline-snapshot

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing Web App Development API Development Custom Software Talk to DEV.co

phpunit-snapshot-assertions FAQ

What happens if I change code and the snapshot diff is legitimate?

Run the `update-snapshots` command or set UPDATE_SNAPSHOTS=true to update the persisted snapshot. Always review the diff in version control before committing to ensure it reflects intended changes.

Can I use snapshot assertions alongside traditional assertions?

Yes. The MatchesSnapshots trait coexists with PHPUnit's standard assertions; mix snapshot and explicit assertions freely within a single test.

Do snapshots work with dynamic values like timestamps or UUIDs?

Not directly. You must remove or mock dynamic values before assertion, or use a different testing strategy. Snapshot testing assumes deterministic, repeatable output.

What is the performance impact of image snapshot testing?

Image snapshots using spatie/pixelmatch-php can be slower than hash-based file snapshots due to pixel-level comparison. Profile in your CI environment and adjust threshold or frequency as needed.

Software developers & web developers for hire

From first prototype to production, DEV.co delivers software development services around tools like phpunit-snapshot-assertions. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source testing and beyond.

Ready to Reduce Test Maintenance?

Snapshot testing cuts down on brittle assertions and boilerplate. Integrate phpunit-snapshot-assertions into your PHP test suite today—or let our team guide your testing strategy.

Talk to DEV.co Schedule a Consultation