Merge branch 'release/1.7.0' into main

skuzzle · Dec 19, 2022 · 728e198 · 728e198
2 parents d17f682 + 8cf8cab
commit 728e198
Show file tree

Hide file tree

Showing 109 changed files with 3,863 additions and 4,191 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -1 +1,2 @@
-snapshot-tests-core/src/test/resources/de/skuzzle/test/snapshots/impl/FailingSnapshotTests$FailBecauseSnapshotMismatchWithWhitespaces_snapshots/testWithSnapshot_0.snapshot eol=crlf
+snapshot-tests-core/src/test/resources/de/skuzzle/test/snapshots/impl/FailingSnapshotTests$FailBecauseSnapshotMismatchWithWhitespaces_snapshots/testWithSnapshot_0.snapshot eol=crlf
+snapshot-tests-core/src/test/resources/de/skuzzle/test/snapshots/impl/FailingSnapshotTestsNew$FailBecauseSnapshotMismatchWithWhitespaces_snapshots/testWithSnapshot_0.snapshot eol=crlf
diff --git a/.gitignore b/.gitignore
@@ -18,4 +18,7 @@ target
 # IntelliJ
 .idea/
 *.iml
-.flattened-pom.xml
+*.flattened-pom.xml
+
+*.snapshot_raw
+*.snapshot_actual
diff --git a/README.md b/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=1.6.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.6.1/jar)
-[![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.6.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-core/1.6.1)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.7.0/jar)
+[![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.0&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-core/1.7.0)
 [![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)
 
@@ -13,17 +13,17 @@ serialized version of the object during the first test execution and during subs
 actual object against the stored snapshot.
 
 Supported snapshot formats:
-- [x] generic plain text via [snapshot-tests-core](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-core/1.6.1/jar)
-- [x] Json via [snapshot-tests-jackson](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jackson/1.6.1/jar)
-- [x] XML via [snapshot-tests-jaxb](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb/1.6.1/jar)
-- [x] HTML via [snapshot-tests-html](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-html/1.6.1/jar)
+- [x] generic plain text via [snapshot-tests-core](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-core/1.7.0/jar)
+- [x] Json via [snapshot-tests-jackson](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jackson/1.7.0/jar)
+- [x] XML via [snapshot-tests-jaxb](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb/1.7.0/jar) xor [snapshot-tests-jaxb-jakarta](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb-jakarta/1.7.0/jar)
+- [x] HTML via [snapshot-tests-html](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-html/1.7.0/jar)
 
 Read more about snapshot testing in this accompanying [blog post](https://simon.taddiken.net/the-case-for-snapshot-testing/).
 
 ### Latest Maven Central coordinates
 
 Please check out the GitHub release page to find Maven & Gradle coordinates for the latest 
-release [1.6.1](https://github.com/skuzzle/snapshot-tests/releases/tag/v1.6.1)
+release [1.7.0](https://github.com/skuzzle/snapshot-tests/releases/tag/v1.7.0)
 
 ## Quick start
 _(assumes using `snapshot-tests-jackson` artifact)_
@@ -123,8 +123,8 @@ void testSnapshotToString(Snapshot snapshot) throws Exception {
 
 ### Structural assertions
 Once serialized, the library uses `StructuralAssertions` to compare two serialized objects. By default, we use 
-`xml-unit` for comparing xmls and `jsonassert` for comparing jsons. Generic text comparison is implemented using the 
-awesome `diff_match_patch` class from Neil Fraser.
+`xml-unit` for comparing xmls and `jsonassert` for comparing jsons. Generic text comparison is implemented using `java-diff-utils`.
+
 When using a custom `SnapshotSerializer` you can also supply a custom `StructuralAssertions` implementation to implement
 comparisons specific to your serialization format.
 
@@ -212,4 +212,27 @@ will log a warning with the found orphan. You can temporarily place the `@Delete
 snapshot test class to have those files deleted automatically.
 
 **Warning:** Deleting orphans should be handled with care. There might be raw occasions where we falsely detect a 
-snapshot file as orphan (especially if you are running only parts of your test suite or have disabled tests).
+snapshot file as orphan (especially if you are running only parts of your test suite or have disabled tests).
+
+### Configuring some more details
+**New**
+Since version `1.7.0` there is a new `@SnapshotTestOptions` annotation that can either be placed on a test method or 
+test class. It allows to configure some details of the snapshot testing engine.
+
+#### Generating additional context files
+Besides persisting the actual snapshot file, the framework can be advised to generate additional context files via 
+`@SnapshotTestOptions.alwaysPersistActualResult()` and `@SnapshotTestOptions.alwaysPersistRawResult()`.
+Disregarding the outcome of the snapshot assertion, these options will advises the framework to always create a file
+containing the latest actual test results. The `..._raw` file will contain the pure serialized actual result without 
+the snapshot header.
+
+Note that these context files should _not_ be checked into the SCM. You should add these two lines to your `.gitignore`
+file:
+```
+*.snapshot_raw
+*.snapshot_actual
+```
+
+#### Showing more context in unified diffs
+Using `@SnapshotTestOptions.textDiffContextLines()` you can advise the framework to print more lines surrounding a
+detected change in the unified diffs. Per default, we will only print 5 lines around a change.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,133 +1,168 @@
-* Deprecated property `DirectoriesFrom.directory` should not be mandatory
-
+* [#19](https://github.com/skuzzle/snapshot-tests/issues/19): Deprecate the whole `@EnabledSnapshotTests` annotation in favor of annotation with same name within `junit5` package
+* [#30](https://github.com/skuzzle/snapshot-tests/issues/30): Deprecate `EnableSnapshotTests.softAssertions`. Soft assertions will no longer be supported in the next major version
+* [#32](https://github.com/skuzzle/snapshot-tests/issues/32): Support for jakarta namespaces via new `snapshot-tests-jaxb-jakarta` module
+* [#47](https://github.com/skuzzle/snapshot-tests/issues/47): Add new `SnapshotTestOptions` annotation which allows to configure some detailed aspects of the snapshot engine
+* Deprecate `EnableSnapshotTests.snapshotDirectory` in favor of new annotation `@SnapshotDirectory`
+* Deprecate `SnapshotTestResult.serializedSnapshot()` in favor of `SnapshotTestResult.snapshotFile()`
+* Add `SnapshotTestResult.serializedActual()`
+* Add `SnapshotTestResult.actualResultFile()`
+* Add `SnapshotTestResult.rawActualResultFile()`
+* Add the possibility to configure the number of context lines printed around a change in the default unified diff via `@SnapshotTestOptions.textDiffContextLines()`
+* Add the possibility to always persist the latest actual result as a sibling file of the real `.snapshot` file via `@SnapshotTestOptions.alwaysPersistActualResult()`
+* Add the possibility to additionally persist the raw actual result in a sibling file of the real `.snapshot` file via `@SnapshotTestOptions.alwaysPersistRawResult()`. The raw result does not contain the snapshot header information.
+* Improve compatibility with JUnit5's `@Nested` tests (general support for `@Nested` is still experimental though)
+* Unified diffs within assertion failure messages now come with full line information
+
+
+_Note_: This release comes with a few major deprecations that are preparing our transition to the next major version 
+that is 2.0. That version will likely see all those deprecated methods to be removed. In general, simple drop in 
+replacements are provided and documented to ensure an easy migration.
 
 Maven Central coordinates for this release:
 
 ## BOM Artifact
 Manages the versions of all modules in case you are using multiple in your project
 
-[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.6.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.6.1/jar)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.7.0/jar)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-bom</artifactId>
-    <version>1.6.1</version>
+    <version>1.7.0</version>
     <type>pom</type>
     <scope>import</scope>
 </dependency>
 ```
 
 ```
-testImplementation(platform("de.skuzzle.test:snapshot-tests-bom:1.6.1"))
+testImplementation(platform("de.skuzzle.test:snapshot-tests-bom:1.7.0"))
 ```
 
 ## Artifacts
 If you only need text based snapshots:
 
-[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.6.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-core/1.6.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.6.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-core/1.6.1)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-core/1.7.0/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.0&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-core/1.7.0)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-core</artifactId>
-    <version>1.6.1</version>
+    <version>1.7.0</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-core:1.6.1'
-testImplementation("de.skuzzle.test:snapshot-tests-core:1.6.1")
+testImplementation 'de.skuzzle.test:snapshot-tests-core:1.7.0'
+testImplementation("de.skuzzle.test:snapshot-tests-core:1.7.0")
 ```
 
 If you need json based snapshots (includes `-core`):
 
-[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.6.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jackson/1.6.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.6.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-jackson/1.6.1)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jackson/1.7.0/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.0&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-jackson/1.7.0)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-jackson</artifactId>
-    <version>1.6.1</version>
+    <version>1.7.0</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-jackson:1.6.1'
-testImplementation("de.skuzzle.test:snapshot-tests-jackson:1.6.1")
+testImplementation 'de.skuzzle.test:snapshot-tests-jackson:1.7.0'
+testImplementation("de.skuzzle.test:snapshot-tests-jackson:1.7.0")
 ```
 
-If you need xml based snapshots (includes `-core`):
+If you need xml based snapshots using `javax.xml` legacy namespaces (includes `-core`):
 
-[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.6.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb/1.6.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.6.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-jaxb/1.6.1)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb/1.7.0/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.0&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-jaxb/1.7.0)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-jaxb</artifactId>
-    <version>1.6.1</version>
+    <version>1.7.0</version>
+    <scope>test</scope>
+</dependency>
+```
+
+```
+testImplementation 'de.skuzzle.test:snapshot-tests-jaxb:1.7.0'
+testImplementation("de.skuzzle.test:snapshot-tests-jaxb:1.7.0")
+```
+
+If you need xml based snapshots using new `jakarta.xml` namespaces (includes `-core`):
+
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb-jakarta/1.7.0/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.0&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-jaxb-jakarta/1.7.0)
+
+```xml
+<dependency>
+    <groupId>de.skuzzle.test</groupId>
+    <artifactId>snapshot-tests-jaxb-jakarta</artifactId>
+    <version>1.7.0</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-jaxb:1.6.1'
-testImplementation("de.skuzzle.test:snapshot-tests-jaxb:1.6.1")
+testImplementation 'de.skuzzle.test:snapshot-tests-jaxb-jakarta:1.7.0'
+testImplementation("de.skuzzle.test:snapshot-tests-jaxb-jakarta:1.7.0")
 ```
 
 If you need HTML based snapshots (includes `-core`):
 
-[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.6.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-html/1.6.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.6.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-html/1.6.1)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-html/1.7.0/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.0&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-html/1.7.0)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-html</artifactId>
-    <version>1.6.1</version>
+    <version>1.7.0</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-html:1.6.1'
-testImplementation("de.skuzzle.test:snapshot-tests-html:1.6.1")
+testImplementation 'de.skuzzle.test:snapshot-tests-html:1.7.0'
+testImplementation("de.skuzzle.test:snapshot-tests-html:1.7.0")
 ```
 
 ## Experimental
 Directory Params
 
-[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.6.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-directory-params/1.6.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.6.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-directory-params/1.6.1)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-directory-params/1.7.0/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.0&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-directory-params/1.7.0)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-directory-params</artifactId>
-    <version>1.6.1</version>
+    <version>1.7.0</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-directory-params:1.6.1'
-testImplementation("de.skuzzle.test:snapshot-tests-directory-params:1.6.1")
+testImplementation 'de.skuzzle.test:snapshot-tests-directory-params:1.7.0'
+testImplementation("de.skuzzle.test:snapshot-tests-directory-params:1.7.0")
 ```
 
 Object normalization
 
-[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.6.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-normalize/1.6.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.6.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-normalize/1.6.1)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-normalize/1.7.0/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.0&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-normalize/1.7.0)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-normalize</artifactId>
-    <version>1.6.1</version>
+    <version>1.7.0</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-normalize:1.6.1'
-testImplementation("de.skuzzle.test:snapshot-tests-normalize:1.6.1")
+testImplementation 'de.skuzzle.test:snapshot-tests-normalize:1.7.0'
+testImplementation("de.skuzzle.test:snapshot-tests-normalize:1.7.0")
 ```
diff --git a/pom.xml b/pom.xml
@@ -9,7 +9,7 @@
 
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-parent</artifactId>
-    <version>1.6.1</version>
+    <version>1.7.0</version>
     <packaging>pom</packaging>
 
     <name>Snapshot Tests Parent</name>
@@ -33,8 +33,12 @@
         <version.assertj>3.22.0</version.assertj>
         <version.opentest4j>1.2.0</version.opentest4j>
 
-        <version.jaxb-api>2.3.1</version.jaxb-api>
-        <version.glassfish-jaxb>2.3.3</version.glassfish-jaxb>
+        <version.java-diff-utils>4.12</version.java-diff-utils>
+
+        <version.jaxb-api-legacy>2.3.1</version.jaxb-api-legacy>
+        <version.glassfish-jaxb-legacy>2.3.3</version.glassfish-jaxb-legacy>
+        <version.glassfish-jaxb-jakarta>4.0.1</version.glassfish-jaxb-jakarta>
+
         <version.xmlunit>2.9.0</version.xmlunit>
         <version.jsoup>1.15.3</version.jsoup>
 
@@ -52,6 +56,7 @@
         <module>snapshot-tests-normalize</module>
         <module>snapshot-tests-jackson</module>
         <module>snapshot-tests-jaxb</module>
+        <module>snapshot-tests-jaxb-jakarta</module>
         <module>snapshot-tests-html</module>
         <module>snapshot-tests-xmlunit</module>
         <module>snapshot-tests-directory-params</module>