From fbd8e7fff1202cf784096e990800df5a09ee0b18 Mon Sep 17 00:00:00 2001 From: Benedikt Waldvogel Date: Fri, 16 Oct 2026 20:41:32 +0200 Subject: [PATCH 1/7] Fix grammar and spelling in README --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 1cf20ef..25b806a 100644 --- a/README.md +++ b/README.md @@ -25,17 +25,17 @@ When we run this test for the first time, it will create the following files: ``` actual value ``` - - `data/test/validation/MyTest_myTestMethod.txt` (this one is prefilled automatically once during the first test run; on consecutive runs it will not be modified automatically) containing + - `data/test/validation/MyTest_myTestMethod.txt` (this one is prefilled automatically once during the first test run; on subsequent runs it will not be modified automatically) containing ``` === new file "data/test/validation/MyTest_myTestMethod.txt" === actual value ``` -The test will fail as long as these two files are different. It’s the developer’s job to manually review the content of the `validation` file and remove the "new file" marker to make the test passing. +The test will fail as long as these two files are different. It’s the developer’s job to manually review the content of the `validation` file and remove the "new file" marker to make the test pass. The reviewed validation file is then committed to the SCM repository together with the test itself. -Starting from this point `validation` file is the expected value of the test. +Starting from this point, the `validation` file is the expected value of the test. -Any change to `"actual value"` will cause the test to fail and in this case the developer has to compare the content of `output` file with `validation` and if satisfied copy `output` to `validation` - this makes the test green. +Any change to `"actual value"` will cause the test to fail and in this case the developer has to compare the content of the `output` file with the `validation` file and if satisfied copy `output` to `validation` - this makes the test green. We recommend using a good diffing tool, such as the built-in differ of IntelliJ or [Meld][meld], that allows you to diff the two directories `data/test/actual` vs `data/test/validation`. We also provide an [IntelliJ plugin][intellij_plugin] that diffs the two directories with one shortcut. @@ -68,15 +68,15 @@ testImplementation 'de.cronn:validation-file-assertions:{version}' * Let your test class implement the `JUnit5ValidationFileAssertions` interface if you are using JUnit5, otherwise use `ValidationFileAssertions` -* Pick suitable `assertWithFile` method and enjoy your first validation file assertion. +* Pick a suitable `assertWithFile` method and enjoy your first validation file assertion. ## Custom validation files directory -It is possible to customize path where validation files are stored, in order to do that: +It is possible to customize the path where validation files are stored, in order to do that: -* Implement `de.cronn.assertions.validationfile.config.Configure` and override method `getDataDirectory()` with path to desired location. +* Implement `de.cronn.assertions.validationfile.config.Configure` and override the method `getDataDirectory()` with path to desired location. -* Register implemented configuration via Java Service Provider interface (namely: put fully qualified configuration class name in `resources/META-INF/services/de.cronn.assertions.validationfile.config.Configuration`) +* Register the implemented configuration via Java Service Provider interface (namely: put fully qualified configuration class name in `resources/META-INF/services/de.cronn.assertions.validationfile.config.Configuration`) ## Soft Assertions @@ -112,7 +112,7 @@ class MyTest implements JUnit5ValidationFileAssertions { ## See also -* [Intellij plugin for validation file comparison][intellij_plugin] +* [IntelliJ plugin for validation file comparison][intellij_plugin] * [File snapshots for Playwright and Vitest][frontend_file_snapshots] [meld]: https://meldmerge.org/ From 3baf2be6ed5c59db6d77586bc2389f68cc872752 Mon Sep 17 00:00:00 2001 From: Benedikt Waldvogel Date: Fri, 16 Oct 2026 20:41:52 +0200 Subject: [PATCH 2/7] Fix output directory and configuration interface name in README --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 25b806a..7f467b7 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Starting from this point, the `validation` file is the expected value of the tes Any change to `"actual value"` will cause the test to fail and in this case the developer has to compare the content of the `output` file with the `validation` file and if satisfied copy `output` to `validation` - this makes the test green. -We recommend using a good diffing tool, such as the built-in differ of IntelliJ or [Meld][meld], that allows you to diff the two directories `data/test/actual` vs `data/test/validation`. +We recommend using a good diffing tool, such as the built-in differ of IntelliJ or [Meld][meld], that allows you to diff the two directories `data/test/output` vs `data/test/validation`. We also provide an [IntelliJ plugin][intellij_plugin] that diffs the two directories with one shortcut. ## Quickstart @@ -74,7 +74,7 @@ testImplementation 'de.cronn:validation-file-assertions:{version}' It is possible to customize the path where validation files are stored, in order to do that: -* Implement `de.cronn.assertions.validationfile.config.Configure` and override the method `getDataDirectory()` with path to desired location. +* Implement `de.cronn.assertions.validationfile.config.Configuration` and override the method `getDataDirectory()` with path to desired location. * Register the implemented configuration via Java Service Provider interface (namely: put fully qualified configuration class name in `resources/META-INF/services/de.cronn.assertions.validationfile.config.Configuration`) From ea8ee036b517683779ace5f49b0a26ffa3a82543 Mon Sep 17 00:00:00 2001 From: Benedikt Waldvogel Date: Sun, 18 Oct 2026 10:29:48 +0200 Subject: [PATCH 3/7] Document Gradle integration in README --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index 7f467b7..8b0bf98 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,26 @@ testImplementation 'de.cronn:validation-file-assertions:{version}' * Pick a suitable `assertWithFile` method and enjoy your first validation file assertion. +## Gradle integration + +Declare the validation files as inputs and the output files as outputs of the `test` task. +Otherwise, Gradle considers the task up-to-date after a validation file was changed. +`PathSensitivity.RELATIVE` keeps the build cache reusable across different checkout locations. + +```kotlin +tasks.test { + inputs.files("data/test/validation").withPathSensitivity(PathSensitivity.RELATIVE) + outputs.dir("data/test/output") + outputs.dir("data/test/tmp") +} + +tasks.clean { + delete("data/test/output", "data/test/tmp") +} +``` + +We also recommend excluding `data/test/output` and `data/test/tmp` in IntelliJ (e.g. via `idea.module.excludeDirs` of the Gradle `idea` plugin), so that their content is not indexed and doesn’t show up in search results. + ## Custom validation files directory It is possible to customize the path where validation files are stored, in order to do that: From ef13495bac5c393aac8de68bdc16f3c868ee5656 Mon Sep 17 00:00:00 2001 From: Benedikt Waldvogel Date: Sun, 18 Oct 2026 10:35:47 +0200 Subject: [PATCH 4/7] Document MarkdownTable in README --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index 8b0bf98..1fae544 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,24 @@ class MyTest implements JUnit5ValidationFileAssertions { } ``` +## Markdown tables + +Tabular data is easiest to review as a table. `MarkdownTable` renders rows as an aligned Markdown table: + +```java +MarkdownTable table = new MarkdownTable(List.of("Name", "Price")); +table.addRow("Coffee", 2.5); +table.addRow("Croissant", 1.9); +assertWithFile(table.toString(), FileExtensions.MD); +``` + +``` +| Name | Price | +|-----------|-------| +| Coffee | 2.5 | +| Croissant | 1.9 | +``` + ## See also * [IntelliJ plugin for validation file comparison][intellij_plugin] From 428ac1ea6d6fb5d987d2e917a66488a18a752917 Mon Sep 17 00:00:00 2001 From: Benedikt Waldvogel Date: Sun, 18 Oct 2026 10:38:17 +0200 Subject: [PATCH 5/7] Document normalization and determinism in README --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 1fae544..c00a1d8 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,23 @@ It is possible to customize the path where validation files are stored, in order * Register the implemented configuration via Java Service Provider interface (namely: put fully qualified configuration class name in `resources/META-INF/services/de.cronn.assertions.validationfile.config.Configuration`) +## Normalization + +Validation files only work with deterministic output (see also our [stance on determinism](https://github.com/cronn#determinism)). +Where possible, make the output itself deterministic, for example by using ordered collections and a fixed clock, locale and time zone. +Values that are random by nature, such as generated UUIDs, can be replaced by stable placeholders using a `ValidationNormalizer`: + +```java +assertWithJsonFile(json, new UuidNormalizer()); +``` + +```json +{"id": "UUID_1", "parentId": "UUID_1", "otherId": "UUID_2"} +``` + +Equal UUIDs get the same placeholder, so references between them remain visible. +See the `normalization` and `replacements` packages for further normalizers, such as `IdNormalizer`, `SimpleRegexReplacement` and `JsonReplacerBuilder`. + ## Soft Assertions File based validation can be combined with [AssertJ’s soft assertions][assertj_soft_assertions]. From 67285684ac7a813713ff4198897edc8162e3ecee Mon Sep 17 00:00:00 2001 From: Benedikt Waldvogel Date: Sun, 18 Oct 2026 10:39:52 +0200 Subject: [PATCH 6/7] Restructure README Getting started section as numbered steps --- README.md | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index c00a1d8..a794557 100644 --- a/README.md +++ b/README.md @@ -40,35 +40,35 @@ Any change to `"actual value"` will cause the test to fail and in this case the We recommend using a good diffing tool, such as the built-in differ of IntelliJ or [Meld][meld], that allows you to diff the two directories `data/test/output` vs `data/test/validation`. We also provide an [IntelliJ plugin][intellij_plugin] that diffs the two directories with one shortcut. -## Quickstart -* Add the dependency +## Getting started -### Gradle -```gradle -testImplementation 'de.cronn:validation-file-assertions:{version}' -``` +1. Add the dependency -### Maven -```xml - - de.cronn - validation-file-assertions - {version} - test - -``` + **Gradle (Kotlin DSL)** + ```kotlin + testImplementation("de.cronn:validation-file-assertions:{version}") + ``` -* Configure your SCM + **Maven** + ```xml + + de.cronn + validation-file-assertions + {version} + test + + ``` - `.gitignore` - ``` - data/test/output/ - data/test/tmp/ - ``` +2. Exclude the output files from your SCM, e.g. in `.gitignore` + + ``` + data/test/output/ + data/test/tmp/ + ``` -* Let your test class implement the `JUnit5ValidationFileAssertions` interface if you are using JUnit5, otherwise use `ValidationFileAssertions` +3. Let your test class implement the `JUnit5ValidationFileAssertions` interface if you are using JUnit5, otherwise use `ValidationFileAssertions` -* Pick a suitable `assertWithFile` method and enjoy your first validation file assertion. +4. Pick a suitable `assertWithFile` method and enjoy your first validation file assertion. ## Gradle integration From 76238eb0938a3e9d92f855ad14cfff36c9d06075 Mon Sep 17 00:00:00 2001 From: Benedikt Waldvogel Date: Sun, 18 Oct 2026 10:44:30 +0200 Subject: [PATCH 7/7] Simplify README title --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a794557..84c9c73 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ [![Apache 2.0](https://img.shields.io/github/license/cronn/validation-file-assertions.svg)](http://www.apache.org/licenses/LICENSE-2.0) [![Valid Gradle Wrapper](https://github.com/cronn/validation-file-assertions/workflows/Validate%20Gradle%20Wrapper/badge.svg)](https://github.com/cronn/validation-file-assertions/actions/workflows/gradle-wrapper-validation.yml) -# "validation-file-assertions" – File Based Assertions for Java +# validation-file-assertions + +File-based assertions for Java. ## Idea shown by example