The gist of snapshot testing is asserting that a set of data hasn't changed compared to a previous version, which is a snapshot of the data, to prevent regressions. The difference between a classic and an is that you don't write the expectation yourself when snapshot testing.

When a snapshot assertion happens for the first time, it creates a snapshot file with the actual output, and marks the test as incomplete. Every subsequent run will compare the output with the existing snapshot file to check for regressions.

Snapshot testing is most useful larger datasets that can change over time, like serializing an object for an XML export or a JSON API endpoint.

Our package, which exposes a trait to add snapshot testing capabilities to your tests, can be installed via composer and is available on GitHub.

I couldn't find any formal origin of snapshot testing. The oldest library I found was one written by Facebook to snapshot test iOS user interfaces. Jest — a JavaScript testing framework which is also made by Facebook — recently popularised snapshot testing, since it provides and excellent workflow for testing user interfaces built with virtual dom libraries like React.

When we expect a changed value, we need to tell the test runner to update the existing snapshots instead of failing the test. This is possible by adding a -d --update-snapshots flag to the phpunit command.

Methods

If you're working with JSON or XML data, you're better off using a dedicated assertMatchesJsonSnapshot or assertMatchesXmlSnapshot method, which will save snapshots as .json or .xml files, and provide a better diff when the snapshot doesn't match.

Snapshot files

Snapshot ids and the snapshot directory's name can be changed in by overriding getSnapshotId and getSnapshotDirectory. Take a look at the readme for a more detailed explanation.

Drivers

Drivers make the package extendable, without the Driver interface snapshot assertions would be limited to JSON, XML and generic values with var_export. A driver handles serializing and matching snapshot data. For example, if your application would make extensive use of YAML files, you could write a YamlDriver to save snapshots as real YAML files and improve PHPUnit's diff output.

Custom drivers can be applied by passing them to assertMatchesSnapshot.

If you're interested in a detailed explanation on writing custom drivers, they have a dedicated section in the readme.

Road To v1.0

There are a some tidbits that require polishing before releasing a first major version. We've decided to tag v1.0 already since we're using this package without issues in a few projects already. The missing features can be added in a a later release.

The --update-snapshots flag needs to be specified after -d, which is meant to set custom php.ini values. PHPUnit doesn't support custom CLI options, but it might be added in a future release (sebastianbergmann/phpunit#2271)

Despite not having a stable version number, there most likely won't be any large breaking changes anymore heading to v1.0.

Thanks @AlexVanderbist for helping out with the integration tests for this package!