Package de.skuzzle.test.snapshots.junit5

Annotation Type EnableSnapshotTests

@Retention(RUNTIME)
@Target(TYPE)
@ExtendWith(de.skuzzle.test.snapshots.junit5.JUnit5SnapshotExtension.class)
@API(status=STABLE,
     since="1.7.0")
public @interface EnableSnapshotTests

Enabling snapshot tests

Enables the snapshot-test capabilities. When you mark a class with this annotation, you can use snapshot assertions by declaring a parameter of type Snapshot in your test case like this:

 @EnableSnapshotTests
 class MyTestClass {

     @Test
     void testSomething(Snapshot snapshot) throws Exception {
         Object actual = ...
         snapshot.assertThat(actual).asText().matchesSnapshotText();
     }
 }
 

asText() will 'serialize' actual test results using Object.toString(). There are additional StructuredDataProvider implementations that allow to serialize snapshots as json, xml or html. To use them, you need to declare their respective maven modules as dependency.

     @Test
     void testSomething(Snapshot snapshot) throws Exception {
         Object actual = ...
         snapshot.assertThat(actual).as(TextSnapshot.text).matchesSnapshotText();
         snapshot.assertThat(actual).as(JsonSnapshot.json).matchesSnapshotText();
         snapshot.assertThat(actual).as(XmlSnapshot.xml).matchesSnapshotText();
     }
 

When providing a structured data format like json/xml (or in general: an implementation of StructuredDataProvider) you can make use of structural assertions to compare snapshots. Depending on the implementation, those might provide better error messages than plain text comparison.

     @Test
     void testSomething(Snapshot snapshot) throws Exception {
         Object actual = ...
         snapshot.assertThat(actual).as(JsonSnapshot.json).matchesSnapshotStructure();
         snapshot.assertThat(actual).as(XmlSnapshot.xml).matchesSnapshotStructure();
     }
 

Parameterized tests

Snapshot tests can be combined with JUnit5's parameterized tests, but only when you provide an explicit name for each snapshot assertion. With the default automatic snapshot naming scheme, snapshots would otherwise be overridden for each parameterized execution.

     @ParameterizedTest
     @Values(strings = { "string1", "string2" })
     void testSomething(String parameter, Snapshot snapshot) throws Exception {
         Object actual = ...

         // BAD: would choose the same snapshot file name 'testSomething_0.snapshot' disregarding the parameter
         // (Note: this could be desired if you expect the same output for all parameters)
         snapshot.assertThat(actual).as...;

         // GOOD: Append the parameter's value to the snapshot name to have separate snapshots per execution
         // This will create snapshots named 'testSomething_0_string1.snapshot' and 'testSomething_0_string2.snapshot'
         snapshot.namedAccordingTo(SnapshotNaming.withParameters(parameter))
                 .assertThat(actual).as...;
 

Updating snapshots

Snapshots can become outdated when your code under test changes on purpose. In that case you can advice the framework to override existing snapshots with your code under test's actual result by placing the annotation ForceUpdateSnapshots on either the whole snapshot test class or on a single test method. You can also use the SnapshotDsl.ChooseAssertions.justUpdateSnapshot() terminal operation of the DSL.

Orphaned snapshots

Snapshot files can become orphans if, for example you rename a test class/method or you change the snapshot assertions within a test. This framework comes with a sophisticated approach for detecting those orphaned files. By default, we will log a warning with the found orphan. You can temporarily place the DeleteOrphanedSnapshots annotation on a snapshot test class to have those files deleted automatically.

See Also:

Snapshot, SnapshotNaming, SnapshotDirectory, DeleteOrphanedSnapshots, ForceUpdateSnapshots