Merge branch 'release/1.7.1' into main

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.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)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.7.1/jar)
+[![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-core/1.7.1)
 [![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.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)
+- [x] generic plain text via [snapshot-tests-core](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-core/1.7.1/jar)
+- [x] Json via [snapshot-tests-jackson](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jackson/1.7.1/jar)
+- [x] XML via [snapshot-tests-jaxb](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb/1.7.1/jar) xor [snapshot-tests-jaxb-jakarta](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb-jakarta/1.7.1/jar)
+- [x] HTML via [snapshot-tests-html](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-html/1.7.1/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.7.0](https://github.com/skuzzle/snapshot-tests/releases/tag/v1.7.0)
+release [1.7.1](https://github.com/skuzzle/snapshot-tests/releases/tag/v1.7.1)
 
 ## Quick start
 _(assumes using `snapshot-tests-jackson` artifact)_
@@ -198,7 +198,7 @@ By default, snapshots are stored in a directory structure according to their tes
 `src/test/resources`. You can change the relative path using 
 
 ```java
-@EnableSnapshotTests(snapshotDirectory = "snapshots")
+SnapshotDirectory("snapshots")
 ```
 Currently it is not possible to use a directory outside `src/test/resources`.
 
@@ -222,7 +222,7 @@ 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
+Disregarding the outcome of the snapshot assertion, these options will advise 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.
 
@@ -235,4 +235,15 @@ file:
 
 #### 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.
+detected change in the unified diffs. Per default, we will only print 5 lines around a change.
+
+
+#### Line number behavior in diffs
+By default, line numbers in the diffs that are rendered in our assertion failure messages reflect the physical line 
+number within the snapshot file. That number differs from the line number within the raw test result data because 
+snapshot files contain some header information at the beginning.
+If you want line numbers in the diffs to reflect the number within the raw data, you can use
+
+```java
+@SnapshotTestOptions(renderLineNumbers = DiffLineNumbers.ACCORDING_TO_RAW_DATA)
+```

RELEASE_NOTES.md

@@ -1,168 +1,151 @@
-* [#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.
+* [#51](https://github.com/skuzzle/snapshot-tests/issues/51): Line numbers in diff are off by number of header lines.
+* HTML comparison used generic `XmlUnitStructuralAssertions` instead of specialized `HtmlStructuralAssertions`
 
 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.7.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.7.0/jar)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.7.1/jar)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-bom</artifactId>
-    <version>1.7.0</version>
+    <version>1.7.1</version>
     <type>pom</type>
     <scope>import</scope>
 </dependency>
 ```
 
 ```
-testImplementation(platform("de.skuzzle.test:snapshot-tests-bom:1.7.0"))
+testImplementation(platform("de.skuzzle.test:snapshot-tests-bom:1.7.1"))
 ```
 
 ## Artifacts
 If you only need text based snapshots:
 
-[![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)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-core/1.7.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-core/1.7.1)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-core</artifactId>
-    <version>1.7.0</version>
+    <version>1.7.1</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-core:1.7.0'
-testImplementation("de.skuzzle.test:snapshot-tests-core:1.7.0")
+testImplementation 'de.skuzzle.test:snapshot-tests-core:1.7.1'
+testImplementation("de.skuzzle.test:snapshot-tests-core:1.7.1")
 ```
 
 If you need json based snapshots (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-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)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jackson/1.7.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-jackson/1.7.1)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-jackson</artifactId>
-    <version>1.7.0</version>
+    <version>1.7.1</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-jackson:1.7.0'
-testImplementation("de.skuzzle.test:snapshot-tests-jackson:1.7.0")
+testImplementation 'de.skuzzle.test:snapshot-tests-jackson:1.7.1'
+testImplementation("de.skuzzle.test:snapshot-tests-jackson:1.7.1")
 ```
 
 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.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)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb/1.7.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-jaxb/1.7.1)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-jaxb</artifactId>
-    <version>1.7.0</version>
+    <version>1.7.1</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")
+testImplementation 'de.skuzzle.test:snapshot-tests-jaxb:1.7.1'
+testImplementation("de.skuzzle.test:snapshot-tests-jaxb:1.7.1")
 ```
 
 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)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb-jakarta/1.7.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-jaxb-jakarta/1.7.1)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-jaxb-jakarta</artifactId>
-    <version>1.7.0</version>
+    <version>1.7.1</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-jaxb-jakarta:1.7.0'
-testImplementation("de.skuzzle.test:snapshot-tests-jaxb-jakarta:1.7.0")
+testImplementation 'de.skuzzle.test:snapshot-tests-jaxb-jakarta:1.7.1'
+testImplementation("de.skuzzle.test:snapshot-tests-jaxb-jakarta:1.7.1")
 ```
 
 If you need HTML based snapshots (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-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)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-html/1.7.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-html/1.7.1)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-html</artifactId>
-    <version>1.7.0</version>
+    <version>1.7.1</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-html:1.7.0'
-testImplementation("de.skuzzle.test:snapshot-tests-html:1.7.0")
+testImplementation 'de.skuzzle.test:snapshot-tests-html:1.7.1'
+testImplementation("de.skuzzle.test:snapshot-tests-html:1.7.1")
 ```
 
 ## Experimental
 Directory Params
 
-[![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)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-directory-params/1.7.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-directory-params/1.7.1)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-directory-params</artifactId>
-    <version>1.7.0</version>
+    <version>1.7.1</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-directory-params:1.7.0'
-testImplementation("de.skuzzle.test:snapshot-tests-directory-params:1.7.0")
+testImplementation 'de.skuzzle.test:snapshot-tests-directory-params:1.7.1'
+testImplementation("de.skuzzle.test:snapshot-tests-directory-params:1.7.1")
 ```
 
 Object normalization
 
-[![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)
+[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.7.1&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-normalize/1.7.1/jar) [![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.7.1&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-normalize/1.7.1)
 
 ```xml
 <dependency>
     <groupId>de.skuzzle.test</groupId>
     <artifactId>snapshot-tests-normalize</artifactId>
-    <version>1.7.0</version>
+    <version>1.7.1</version>
     <scope>test</scope>
 </dependency>
 ```
 
 ```
-testImplementation 'de.skuzzle.test:snapshot-tests-normalize:1.7.0'
-testImplementation("de.skuzzle.test:snapshot-tests-normalize:1.7.0")
+testImplementation 'de.skuzzle.test:snapshot-tests-normalize:1.7.1'
+testImplementation("de.skuzzle.test:snapshot-tests-normalize:1.7.1")
 ```

pom.xml

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

readme/README.md

@@ -198,7 +198,7 @@ By default, snapshots are stored in a directory structure according to their tes
 `src/test/resources`. You can change the relative path using 
 
 ```java
-@EnableSnapshotTests(snapshotDirectory = "snapshots")
+SnapshotDirectory("snapshots")
 ```
 Currently it is not possible to use a directory outside `src/test/resources`.
 
@@ -222,7 +222,7 @@ 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
+Disregarding the outcome of the snapshot assertion, these options will advise 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.
 
@@ -235,4 +235,15 @@ file:
 
 #### 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.
+detected change in the unified diffs. Per default, we will only print 5 lines around a change.
+
+
+#### Line number behavior in diffs
+By default, line numbers in the diffs that are rendered in our assertion failure messages reflect the physical line 
+number within the snapshot file. That number differs from the line number within the raw test result data because 
+snapshot files contain some header information at the beginning.
+If you want line numbers in the diffs to reflect the number within the raw data, you can use
+
+```java
+@SnapshotTestOptions(renderLineNumbers = DiffLineNumbers.ACCORDING_TO_RAW_DATA)
+```