Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 90 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -25,58 +27,95 @@ 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 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
<dependency>
<groupId>de.cronn</groupId>
<artifactId>validation-file-assertions</artifactId>
<version>{version}</version>
<scope>test</scope>
</dependency>
```
**Gradle (Kotlin DSL)**
```kotlin
testImplementation("de.cronn:validation-file-assertions:{version}")
```

**Maven**
```xml
<dependency>
<groupId>de.cronn</groupId>
<artifactId>validation-file-assertions</artifactId>
<version>{version}</version>
<scope>test</scope>
</dependency>
```

2. Exclude the output files from your SCM, e.g. in `.gitignore`

```
data/test/output/
data/test/tmp/
```

3. Let your test class implement the `JUnit5ValidationFileAssertions` interface if you are using JUnit5, otherwise use `ValidationFileAssertions`

4. Pick a suitable `assertWithFile` method and enjoy your first validation file assertion.

* Configure your SCM
## Gradle integration

`.gitignore`
```
data/test/output/
data/test/tmp/
```
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.

* Let your test class implement the `JUnit5ValidationFileAssertions` interface if you are using JUnit5, otherwise use `ValidationFileAssertions`
```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")
}
```

* Pick suitable `assertWithFile` method and enjoy your first validation file assertion.
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 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.Configuration` 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`)

## 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

Expand Down Expand Up @@ -110,9 +149,27 @@ 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]
* [IntelliJ plugin for validation file comparison][intellij_plugin]
* [File snapshots for Playwright and Vitest][frontend_file_snapshots]

[meld]: https://meldmerge.org/
Expand Down
Loading