Merge branch 'release/0.0.6' into main

JenkinsfileRelease

@@ -57,7 +57,7 @@ pipeline {
     stage('Create GitHub release') {
       steps {
         sh 'git checkout main'
-        sh "mvn -B github-release:github-release -Dgithub.release-token=${GITHUB_RELEASE_TOKEN}"
+        sh "mvn -B github-release:github-release -Dgithub.release-token=${GITHUB_RELEASE_TOKEN} -N"
       }
     }
   }

README.md

@@ -1,7 +1,7 @@
 <!-- This file is auto generated during release from readme/README.md -->
 
-[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=0.0.5&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-parent/0.0.5/jar)
-[![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=0.0.5&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-parent/0.0.5)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=0.0.6&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-parent/0.0.6/jar)
+[![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=0.0.6&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-parent/0.0.6)
 [![Coverage Status](https://coveralls.io/repos/github/skuzzle/snapshot-tests/badge.svg?branch=main)](https://coveralls.io/github/skuzzle/snapshot-tests?branch=main)
 [![Twitter Follow](https://img.shields.io/twitter/follow/skuzzleOSS.svg?style=social)](https://twitter.com/skuzzleOSS)
 
@@ -19,50 +19,50 @@ If you only need text based snapshots:
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-core</artifactId>
-    <version>0.0.5</version>
+    <version>0.0.6</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-core:0.0.5'
+testImplementation 'de.skuzzle.test:snapshot-tests-core:0.0.6'
 ```
 
 If you need json based snapshots (includes `-core`):
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-jackson</artifactId>
-    <version>0.0.5</version>
+    <version>0.0.6</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-jackson:0.0.5'
+testImplementation 'de.skuzzle.test:snapshot-tests-jackson:0.0.6'
 ```
 
 If you need xml based snapshots (includes `-core`):
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-jaxb</artifactId>
-    <version>0.0.5</version>
+    <version>0.0.6</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-jaxb:0.0.5'
+testImplementation 'de.skuzzle.test:snapshot-tests-jaxb:0.0.6'
 ```
 
 ## Quick start
 _(assumes using `snapshot-tests-jackson` artifact)_
 
-Annotate your test class with `@SnapshotAssertions` and declare a `Snapshot` parameter in your test case:
+Annotate your test class with `@EnableSnapshotTests` and declare a `Snapshot` parameter in your test case:
 
 ```java
-@SnapshotAssertions
+@EnableSnapshotTests
 class ComplexTest {
 
     private WhatEverService classUnderTest = ...;
@@ -98,7 +98,7 @@ implementation change:
 persisted snapshots with the current test results. You can do so by setting the `updateSnapshots` attribute like so:
 
 ```java
-@SnapshotAssertions(forceUpdateSnapshots = true)
+@EnableSnapshotTests(forceUpdateSnapshots = true)
 ```
 
 You can also update snapshots for individual assertions by replacing any of the `matchesSnapshot...` calls with 
@@ -147,20 +147,23 @@ You can create multiple snapshots using `snapshot.assertThat(...)` from within a
 assign each snapshot a consecutive number.
 
 ### Dealing with random values
-A common source of problems are random values within the snapshoted data such as dates or generated ids. This framework
-comes with no means to resolve those issues. Instead you should design your code so that such randomness can easily be 
-mocked away. For example:
+A common source of problems are random values within the snapshot data such as dates or generated ids. This framework
+comes with no means to resolve those issues. Instead you should design your code up front so that such randomness can 
+easily be mocked away. For example:
 * Instead of using `LocalDateTime.now()` make your code use a shared `Clock` instance that is replacible in tests and 
 use `LocalDateTime.now(clock)`
 * More generally put: If your code uses random values in any place, consider to use a strategy interface instead which 
 can be replaced with a deterministic mock during testing.
+* As a last resort, you can implement some normalization. Either post-process your actual test result before taking the
+ snapshot or implement a `SnapshotSerializer` which does the normalization. You could also implement 
+ `StructralAssertions` in a way that it ignores such random values during comparison. 
 
 ### Changing the snapshot directory
 By default, snapshots are stored in a directory structure according to their test-class's package name relative to 
 `src/test/resources`. You can change the relative path using 
 
 ```java
-@SnapshotAssertions(snapshotDirectory = "snapshots")
+@EnableSnapshotTests(snapshotDirectory = "snapshots")
 ```
 Currently it is not possible to use a directory outside `src/test/resources`.
 

RELEASE_NOTES.md

@@ -1,8 +1,6 @@
-[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=0.0.5&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-parent/0.0.5/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=0.0.5&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-parent/0.0.5)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=0.0.6&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-parent/0.0.6/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=0.0.6&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-parent/0.0.6)
 
-* Refactor to multi module project
-* [#6](https://github.com/skuzzle/snapshot-tests/issues/6) Allow to specify explicit snapshot name
-* [#7](https://github.com/skuzzle/snapshot-tests/issues/7) Write snapshot information to headers (**breaking**)
+* [#11](https://github.com/skuzzle/snapshot-tests/issues/11) Rename `@SnapshotAssertions` to `@EnableSnapshotTests` (**breaking**)
 
 Maven Central coordinates for this release:
 
@@ -11,39 +9,39 @@ If you only need text based snapshots:
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-core</artifactId>
-    <version>0.0.5</version>
+    <version>0.0.6</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-core:0.0.5'
+testImplementation 'de.skuzzle.test:snapshot-tests-core:0.0.6'
 ```
 
 If you need json based snapshots (includes `-core`):
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-jackson</artifactId>
-    <version>0.0.5</version>
+    <version>0.0.6</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-jackson:0.0.5'
+testImplementation 'de.skuzzle.test:snapshot-tests-jackson:0.0.6'
 ```
 
 If you need xml based snapshots (includes `-core`):
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-jaxb</artifactId>
-    <version>0.0.5</version>
+    <version>0.0.6</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-jaxb:0.0.5'
+testImplementation 'de.skuzzle.test:snapshot-tests-jaxb:0.0.6'
 ```

pom.xml

@@ -10,7 +10,7 @@
 
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-parent</artifactId>
-    <version>0.0.5</version>
+    <version>0.0.6</version>
     <packaging>pom</packaging>
 
     <name>Snapshot Tests Parent</name>

readme/README.md

@@ -59,10 +59,10 @@ testImplementation '${project.groupId}:snapshot-tests-jaxb:${project.version}'
 ## Quick start
 _(assumes using `snapshot-tests-jackson` artifact)_
 
-Annotate your test class with `@SnapshotAssertions` and declare a `Snapshot` parameter in your test case:
+Annotate your test class with `@EnableSnapshotTests` and declare a `Snapshot` parameter in your test case:
 
 ```java
-@SnapshotAssertions
+@EnableSnapshotTests
 class ComplexTest {
 
     private WhatEverService classUnderTest = ...;
@@ -98,7 +98,7 @@ implementation change:
 persisted snapshots with the current test results. You can do so by setting the `updateSnapshots` attribute like so:
 
 ```java
-@SnapshotAssertions(forceUpdateSnapshots = true)
+@EnableSnapshotTests(forceUpdateSnapshots = true)
 ```
 
 You can also update snapshots for individual assertions by replacing any of the `matchesSnapshot...` calls with 
@@ -147,20 +147,23 @@ You can create multiple snapshots using `snapshot.assertThat(...)` from within a
 assign each snapshot a consecutive number.
 
 ### Dealing with random values
-A common source of problems are random values within the snapshoted data such as dates or generated ids. This framework
-comes with no means to resolve those issues. Instead you should design your code so that such randomness can easily be 
-mocked away. For example:
+A common source of problems are random values within the snapshot data such as dates or generated ids. This framework
+comes with no means to resolve those issues. Instead you should design your code up front so that such randomness can 
+easily be mocked away. For example:
 * Instead of using `LocalDateTime.now()` make your code use a shared `Clock` instance that is replacible in tests and 
 use `LocalDateTime.now(clock)`
 * More generally put: If your code uses random values in any place, consider to use a strategy interface instead which 
 can be replaced with a deterministic mock during testing.
+* As a last resort, you can implement some normalization. Either post-process your actual test result before taking the
+ snapshot or implement a `SnapshotSerializer` which does the normalization. You could also implement 
+ `StructralAssertions` in a way that it ignores such random values during comparison. 
 
 ### Changing the snapshot directory
 By default, snapshots are stored in a directory structure according to their test-class's package name relative to 
 `src/test/resources`. You can change the relative path using 
 
 ```java
-@SnapshotAssertions(snapshotDirectory = "snapshots")
+@EnableSnapshotTests(snapshotDirectory = "snapshots")
 ```
 Currently it is not possible to use a directory outside `src/test/resources`.
 

readme/RELEASE_NOTES.md

@@ -1,8 +1,6 @@
 [![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=${project.version}&color=blue)](https://search.maven.org/artifact/${project.groupId}/${project.artifactId}/${project.version}/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=${project.version}&color=orange)](http://www.javadoc.io/doc/${project.groupId}/${project.artifactId}/${project.version})
 
-* Refactor to multi module project
-* [#6](https://github.com/skuzzle/snapshot-tests/issues/6) Allow to specify explicit snapshot name
-* [#7](https://github.com/skuzzle/snapshot-tests/issues/7) Write snapshot information to headers (**breaking**)
+* [#11](https://github.com/skuzzle/snapshot-tests/issues/11) Rename `@SnapshotAssertions` to `@EnableSnapshotTests` (**breaking**)
 
 Maven Central coordinates for this release:
 

snapshot-tests-core/pom.xml

@@ -5,7 +5,7 @@
     <parent>
         <groupId>de.skuzzle.test</groupId>
         <artifactId>snapshot-tests-parent</artifactId>
-        <version>0.0.5</version>
+        <version>0.0.6</version>
     </parent>
 
     <artifactId>snapshot-tests-core</artifactId>

snapshot-tests-core/src/main/java/de/skuzzle/test/snapshots/SnapshotAssertions.java → snapshot-tests-core/src/main/java/de/skuzzle/test/snapshots/EnableSnapshotTests.java

@@ -10,31 +10,63 @@
 import org.junit.jupiter.api.extension.ExtendWith;
 
 import de.skuzzle.test.snapshots.SnapshotDsl.ChooseAssertions;
+import de.skuzzle.test.snapshots.SnapshotDsl.Snapshot;
 import de.skuzzle.test.snapshots.impl.SnapshotExtension;
 
 /**
  * Enables the snapshot-test capabilities. When you mark a class with this annotation, you
- * can use snapshot assertions like this:
+ * can use snapshot assertions by declaring a parameter of type {@link Snapshot} in your
+ * test case like this:
  *
  * <pre>
- * &#64;SnapshotAssertions
+ * &#64;EnableSnapshotTests
  * class MyTestClass {
  *
  *     &#64;Test
  *     void testSomething(Snapshot snapshot) throws Exception {
  *         Object actual = ...
- *         snapshot.assertThat(actual).asXml().matchesSnapshot();
+ *         snapshot.assertThat(actual).asText().matchesSnapshotText();
  *     }
  * }
  * </pre>
+ * <p>
+ * <code>asText()</code> will 'serialize' actual test results using
+ * {@link Object#toString()}. There are additional {@link StructuredDataBuilder}
+ * implementations that allow to serialize snapshots as json or xml. To use them, you need
+ * to declare their respective maven modules as dependency.
+ *
+ * <pre>
+ *     &#64;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();
+ *     }
+ * </pre>
+ * <p>
+ * When providing a structured data format like json/xml (or in general: an implementation
+ * of {@link StructuredDataBuilder}) you can make use of <em>structural assertions</em> to
+ * compare snapshots. Depending on the implementation, those might provide better error
+ * messages than plain text comparison.
+ *
+ * <pre>
+ *     &#64;Test
+ *     void testSomething(Snapshot snapshot) throws Exception {
+ *         Object actual = ...
+ *         snapshot.assertThat(actual).as(JsonSnapshot.json).matchesSnapshotStructure();
+ *         snapshot.assertThat(actual).as(XmlSnapshot.xml).matchesSnapshotStructure();
+ *     }
+ * </pre>
  *
  * @author Simon Taddiken
+ * @see Snapshot
  * @since ever.
  */
 @Retention(RUNTIME)
 @Target({ TYPE, METHOD })
 @ExtendWith(SnapshotExtension.class)
-public @interface SnapshotAssertions {
+public @interface EnableSnapshotTests {
 
     /**
      * Define the snapshot directory relative to <code>src/test/resources</code>. If this

snapshot-tests-core/src/main/java/de/skuzzle/test/snapshots/SnapshotDsl.java

@@ -22,7 +22,7 @@ public interface SnapshotDsl {
      * </pre>
      *
      * Note that the respective test class must be annotated with
-     * {@link SnapshotAssertions}, otherwise the test framework will not be able to
+     * {@link EnableSnapshotTests}, otherwise the test framework will not be able to
      * resolve the <code>Snapshot</code> parameter of the test method.
      *
      * @author Simon Taddiken
@@ -114,7 +114,7 @@ public interface ChooseAssertions {
          * @since ever
          */
         @Deprecated
-        SnapshotResult justUpdateSnapshot();
+        SnapshotTestResult justUpdateSnapshot();
 
         /**
          * Asserts that the serialized actual test result matches the persisted snapshot
@@ -127,7 +127,7 @@ public interface ChooseAssertions {
          * @since ever
          * @see TextSnapshot
          */
-        SnapshotResult matchesSnapshotText();
+        SnapshotTestResult matchesSnapshotText();
 
         /**
          * Asserts that the serialized actual test result structurally matches the
@@ -140,7 +140,7 @@ public interface ChooseAssertions {
          *             {@link StructuralAssertions#assertEquals(String, String)}.
          * @since ever
          */
-        SnapshotResult matchesAccordingTo(StructuralAssertions structuralAssertions);
+        SnapshotTestResult matchesAccordingTo(StructuralAssertions structuralAssertions);
     }
 
     public interface ChooseStructure extends ChooseAssertions {
@@ -158,7 +158,7 @@ public interface ChooseStructure extends ChooseAssertions {
          *             occurred.
          * @since ever
          */
-        SnapshotResult matchesSnapshotStructure() throws Exception;
+        SnapshotTestResult matchesSnapshotStructure() throws Exception;
 
     }
 }

snapshot-tests-core/src/main/java/de/skuzzle/test/snapshots/SnapshotFile.java

@@ -51,10 +51,21 @@ public static SnapshotFile readFrom(BufferedReader reader) throws IOException {
         return new SnapshotFile(header, snapshot.toString());
     }
 
+    /**
+     * Header information to this snapshot that are written by the framework.
+     *
+     * @return The header.
+     */
     public SnapshotHeader header() {
         return header;
     }
 
+    /**
+     * The serialized snapshot. This is the string that has been produced by the
+     * {@link SnapshotSerializer} in place.
+     *
+     * @return The serialized snapshot string.
+     */
     public String snapshot() {
         return snapshot;
     }