Skip to content

Commit

Permalink
[Gradle Release Plugin] - pre tag commit: 'v1.10.0'.
Browse files Browse the repository at this point in the history
  • Loading branch information
Jenkins committed Mar 28, 2023
2 parents 6b398af + 1dfa2b4 commit 267a653
Show file tree
Hide file tree
Showing 221 changed files with 6,020 additions and 1,196 deletions.
72 changes: 36 additions & 36 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,61 @@
<!-- This file is auto generated during release from readme/README.md -->

[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.9.2&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.9.2/jar)
[![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.9.2&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-core/1.9.2)
[![Reference](https://img.shields.io/static/v1?label=Reference&message=1.9.2&color=orange)](https://skuzzle.github.io/snapshot-tests/reference/1.9.2)
[![Maven Central](https://img.shields.io/static/v1?label=MavenCentral&message=1.10.0&color=blue)](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-bom/1.10.0/jar)
[![JavaDoc](https://img.shields.io/static/v1?label=JavaDoc&message=1.10.0&color=orange)](http://www.javadoc.io/doc/de.skuzzle.test/snapshot-tests-core/1.10.0)
[![Reference](https://img.shields.io/static/v1?label=Reference&message=1.10.0&color=orange)](https://skuzzle.github.io/snapshot-tests/reference/1.10.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/ProjectPolly.svg?style=social)](https://twitter.com/ProjectPolly)

# snapshot-tests
Convenient snapshot testing for JUnit5 and JUnit4.
Convenient snapshot testing for JUnit5 and JUnit4.

This library allows to conveniently assert on the structure and contents of complex objects. It does so by storing a
This library allows to conveniently assert on the structure and contents of complex objects. It does so by storing a
serialized version of the object during the first test execution and during subsequent test executions, compare the
actual object against the stored snapshot.

- [x] Requires Java 11, supports Java 17

Supported test frameworks:
- [x] JUnit5 (tested against `5.9.2`) via [snapshot-tests-junit5](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-junit5/1.9.2/jar)
- [x] JUnit4 (tested against `4.13.2`) via [snapshot-tests-junit4](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-junit4/1.9.2/jar)
- [x] JUnit5 (tested against `5.9.2`) via [snapshot-tests-junit5](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-junit5/1.10.0/jar)
- [x] JUnit4 (tested against `4.13.2`) via [snapshot-tests-junit4](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-junit4/1.10.0/jar)

Supported snapshot formats:
- [x] generic plain text (included by default via [snapshot-tests-core](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-core/1.9.2/jar))
- [x] Json via [snapshot-tests-jackson](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jackson/1.9.2/jar)
- [x] XML via [snapshot-tests-jaxb](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb/1.9.2/jar) xor [snapshot-tests-jaxb-jakarta](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-jaxb-jakarta/1.9.2/jar)
- [x] HTML via [snapshot-tests-html](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-html/1.9.2/jar)
- [x] generic plain text (included by default via [snapshot-tests-core](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-core/1.10.0/jar))
- [x] Json via [snapshot-tests-json](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-json/1.10.0/jar)
- [x] XML via [snapshot-tests-xml](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-xml/1.10.0/jar) xor [snapshot-tests-xml-legacy](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-xml-legacy/1.10.0/jar)
- [x] HTML via [snapshot-tests-html](https://search.maven.org/artifact/de.skuzzle.test/snapshot-tests-html/1.10.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.9.2](https://github.com/skuzzle/snapshot-tests/releases/tag/v1.9.2)
Please check out the GitHub release page to find Maven & Gradle coordinates for the latest
release [1.10.0](https://github.com/skuzzle/snapshot-tests/releases/tag/v1.10.0)

### Reference Documentation
Starting with release `1.8.0` we provide a new external reference documentation:
* [Latest](https://skuzzle.github.io/snapshot-tests/reference/latest): Always points to the latest version
* [1.9.2](https://skuzzle.github.io/snapshot-tests/reference/1.9.2): Points to a specific version
* [1.10.0](https://skuzzle.github.io/snapshot-tests/reference/1.10.0): Points to a specific version

Over the course of the next releases most of the contents of this README will be transitioned into the new reference
Over the course of the next releases most of the contents of this README will be transitioned into the new reference
documentation.

## Quick start
_(assumes using `maven`, `JUnit5` and `snapshot-tests-jackson` artifact)_
_(assumes using `maven`, `JUnit5` and `snapshot-tests-json` artifact)_

Add the following dependencies to your build

```xml
<dependency>
<groupId>de.skuzzle.test</groupId>
<artifactId>snapshot-tests-junit5</artifactId>
<version>1.9.2</version>
<version>1.10.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>de.skuzzle.test</groupId>
<artifactId>snapshot-tests-jackson</artifactId>
<version>1.9.2</version>
<artifactId>snapshot-tests-json</artifactId>
<version>1.10.0</version>
<scope>test</scope>
</dependency>
```
Expand All @@ -77,43 +77,43 @@ class ComplexTest {
```
Snapshot testing workflow:
1. Implement your test cases and add one ore more snapshot assertions as shown above.
2. When you now execute these tests the first time, serialized snapshots of your test results will be persisted
2. When you now execute these tests the first time, serialized snapshots of your test results will be persisted
**and the tests will fail**
3. Execute the same tests again. Now, the framework will compare the test results against the persisted snapshots.
3. Execute the same tests again. Now, the framework will compare the test results against the persisted snapshots.
If your code under test produces deterministic results, tests should now be green
4. Check in the persisted snapshots into your SCM


## Notes on test framework support

### JUnit5
Historically, JUnit5 is the preferred test framework and has always natively been supported. The preferred way of
configuring the build is to add a dependency to `snapshot-tests-junit5` and optionally add a dependency for your
Historically, JUnit5 is the preferred test framework and has always natively been supported. The preferred way of
configuring the build is to add a dependency to `snapshot-tests-junit5` and optionally add a dependency for your
preferred snapshot format (i.e. like `snapshot-tests-jackson`).

### JUnit5 legacy
The `snapshot-tests-junit5` module has been introduced with version `1.8.0`. Prior to that, you would either add a
direct dependency to `snapshot-tests-core` or just use a single dependency to you preferred snapshot format which
would pull in the `-core` module transitively. This setup still works but is discouraged. You will see a warning being
The `snapshot-tests-junit5` module has been introduced with version `1.8.0`. Prior to that, you would either add a
direct dependency to `snapshot-tests-core` or just use a single dependency to you preferred snapshot format which
would pull in the `-core` module transitively. This setup still works but is discouraged. You will see a warning being
printed to `System.err` stating the required migration steps.

> **Warning**
> Starting from version `2.0.0` this scenario will no longer be supported.
### JUnit4
JUnit4 support was introduced with version `1.8.0`. Add a dependency to `snapshot-tests-junit4` and optionally
JUnit4 support was introduced with version `1.8.0`. Add a dependency to `snapshot-tests-junit4` and optionally
add a dependency for your preferred snapshot format like `snapshot-tests-jackson`.

> **Warning**
> In order to seamlessly support the JUnit5 legacy scenario described above, all snapshot format modules will still
> transitively pull in a JUnit5 dependency. Unfortunately this can only be fixed with the next major release. So long you
> In order to seamlessly support the JUnit5 legacy scenario described above, all snapshot format modules will still
> transitively pull in a JUnit5 dependency. Unfortunately this can only be fixed with the next major release. So long you
> might want to add a respective exclusion to your dependency:
```xml
<dependency>
<groupId>de.skuzzle.test</groupId>
<artifactId>snapshot-tests-jackson</artifactId>
<version>1.9.2</version>
<artifactId>snapshot-tests-json</artifactId>
<version>1.10.0</version>
<scope>test</scope>
<exclusions>
<exclusion>
Expand All @@ -127,7 +127,7 @@ add a dependency for your preferred snapshot format like `snapshot-tests-jackson
or

```
testImplementation('de.skuzzle.test:snapshot-tests-jackson:1.9.2') {
testImplementation('de.skuzzle.test:snapshot-tests-json:1.10.0') {
exclude group: 'org.junit.jupiter', module: 'junit-jupiter-api'
}
```
Expand All @@ -138,7 +138,7 @@ testImplementation('de.skuzzle.test:snapshot-tests-jackson:1.9.2') {
### 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
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.

#### Showing more context in unified diffs
Expand All @@ -147,11 +147,11 @@ detected change in the unified diffs. Per default, we will only print 5 lines ar


#### 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
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)
```
```
Loading

0 comments on commit 267a653

Please sign in to comment.