Snapshot-Tests User Guide

This project strongly aims to provide a stable public API with little surprises for clients when they upgrade to a new version. We rely on the principles of semantic versioning and use @API Guardian to communicate the intention of all public classes/methods. Consequently you should not use any public types that are marked as INTERNAL.

The following principles apply:

This documentation pertains to version 1.11.0 of snapshot-tests. The following notable changes have been made since the previous minor version:

The library comes with different modules that can be used and combined to fulfill different testing purposes. As such it is not uncommon that you want to include multiple modules in your project’s dependencies. We provide a BOM artifact for your convenience:

The following modules are managed in the previously mentioned BOM artifact. Follow the remaining documentation to learn how to properly combine them to employ snapshot testing in your own project.

In order to use snapshot-tests you have to answer two simple questions:

This is a very simple quick start example of how to use this framework, using the -junit5 module and no particular snapshot format. Instead, it simply uses the toString() representation of the test result to create a persistable snapshot file.

As shown in the Getting Started section, you need to enable snapshot tests capabilities for your test class by annotating it with @EnabledSnapshotTests. This registers a JUnit5 ArgumentResolver which takes care of injecting a Snapshot instance into your test methods. The Snapshot interface is the entrypoint for the assertion DSL.

If you are using JUnit4, you need to declare the SnapshotRule like this:

Besides the different way of enabling the snapshot testing capabilities there are no further differences between usage in JUnit4 and JUnit5. The Snapshot class is the main entrypoint for writing snapshot assertions.

The framework needs to create a String representation of the test results in order to store it in a snapshot file. Creating such a String representation is referred to as serialization and this aspect is handled by implementations of the SnapshotSerializer interface.

To compare persisted snapshot data against actual test results, the framework serializes the actual test result as well and passes both Strings to an instance of StructuralAssertions.

Though serialization and comparison are handled by different components the aspects are still related. As StructuralAssertions solely work on the String representation it is important that the implementation understands the Strings that have been produced by the SnapshotSerializer (i.e. you should not mix a serializer that produces XML with an StructualAssertions instance that compares JSON).

The Snapshot DSL allows you to configure these aspects separately but also provides a convenient API for configuring the Serializer and Assertions at once via the StructuredData class.

The DSL distinguishes between just text and structured text snapshots. This distinction influences the way in which new test results can be compared to persisted snapshots:

See the section about supported structured data formats to learn more about the different supported structured data formats.

One aspect that makes snapshot testing so powerful is that you can generate the expected output from your code under test itself. This removes the necessity to manually update test cases when the behavior of your code under test changes intentionally. The framework comes with a convenient approach for updating multiple snapshot files at once. You should stick to the following workflow:

You can place the @ForceUpdateSnapshots annotation on either your test method or your whole test class to advise the framework to update the snapshots of all affected assertions.

Snapshots can also be updated globally by passing the -DforceUpdateSnapshots parameter to the JVM. This will update the snapshots of all tests executed within the JVM.

Finally you can replace the call to .matchesSnapshotText() or .matchesSnapshotStructure() of your assertion with .justUpdateSnapshot(). When executing the test the framework will simply override the existing snapshot for this assertion with the passed in actual result.

By convention, snapshots of your test results are persisted as .snapshot files below src/test/resources. The framework will create sub directories according to your test class’s package and name. The snapshot file’s name will be derived from the respective test’s method name.

A snapshot file does not only include the serialized test result but also a small header section containing some meta information. These information are used by the framework to map the snapshot file to the test method and assertion from which it was created.

You can have multiple assertions in the same test case. The framework will assign each snapshot file a consecutive number.

The framework offers a possibility to gracefully disable a snapshot assertion. This means that the assertion will still be registered with the framework in order to not confuse the consecutive numbering. It won’t do any comparison though and thus won’t cause a test failure.

Snapshot tests work well together with JUnit5’s @ParameterizedTest but only if you take care of proper snapshot naming yourself like in this snippet:

This will make each parameter’s value part of the generated snapshot’s file name.

Otherwise, when using the default naming strategy, the framework would choose the same snapshot name for every parameterized execution.

Check out the SnapshotNaming interface for more options regarding snapshot naming.

@Nested test classes are a nice JUnit5 feature to structure tests in a hierarchical fashion. When you put @EnableSnapshotTests on the top level test class, snapshot tests will be enabled automatically for each @Nested class. All options that are normally resolved from annotations on the test class are resolved by first querying the nested class itself and then all of its enclosing parents. The first encountered annotation in that chain wins. Also, each nested test class will by default be assigned an own snapshot directory. You could change this by configuring the directory on a common ancestor.

As learned in the previous section, you can easily have multiple snapshot assertions within the same test method. Naturally, if the first assertion fails, all subsequent assertions will not be executed, thus potentially hiding further problems.

However, there is an option to enable soft assertions. That will advice the framework to collect all assertion failures and report them in a single stack trace at the end.

This library comes with out-of-the-box support for multiple structured data formats. The respective artifacts were already mentioned in the artifacts section in the beginning.

This section explains in detail how to work with each of the different structured data formats and how to fine-tune their comparison behavior.

In general, each structured data format comes with a public builder class that can be used to configure the comparison. This builder can be passed to the DSL when configuring the snapshot assertion. In pseudo-code:

This configures both a SnapshotSerializer and a StructuredAssertions instance for the assertion. Doing so we are effectively configuring two aspects at once:

A common source of problems are random values within the snapshot data such as dates or generated ids. Generally, you should design your code up front so that such randomness can easily be mocked away. For example:

New The latest version of this library comes with a very simple (and experimental) abstraction for customizing the structural comparison. You can use json-path resp. xpath expressions to customize the comparison on a per-node basis.

XML example:

JSON example:

Using stored files as input for your snapshot tests is a great way to quickly create new test cases. You can find details in this blog post.