Skip to content
Merged
Show file tree
Hide file tree
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
34 changes: 32 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,12 +68,35 @@ We also provide an [IntelliJ plugin][intellij_plugin] that diffs the two directo
data/test/tmp/
```

3. Let your test class implement the `JUnit5ValidationFileAssertions` interface if you are using JUnit5, otherwise use `ValidationFileAssertions`
3. Optional, with Gradle: apply the [Gradle plugin](#gradle-integration)

4. Pick a suitable `assertWithFile` method and enjoy your first validation file assertion.
4. Let your test class implement the `JUnit5ValidationFileAssertions` interface if you are using JUnit5, otherwise use `ValidationFileAssertions`

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

## Gradle integration

The [validation files Gradle plugin][gradle_validation_files_plugin] integrates validation files into the Gradle build:

```kotlin
plugins {
id("de.cronn.validation-files") version "{plugin-version}"
}
```

The current `{plugin-version}` is listed on the [Gradle Plugin Portal][gradle_validation_files_plugin_portal].

* Changing a validation file reruns the tests, and the build cache stays reusable across checkout locations.
* `clean` deletes `data/test/output` and `data/test/tmp`.
* `check` fails for validation files that no test wrote anymore, e.g. after a test was renamed or removed.
`deleteUnusedValidationFiles` deletes them.
* IntelliJ excludes `data/test/output` and `data/test/tmp`, so that their content is not indexed and doesn’t show up in search results.

See the [plugin’s README][gradle_validation_files_plugin] for the configuration, e.g. for frontend tests with [file-snapshots][frontend_file_snapshots].

<details>
<summary>Without the plugin</summary>

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.
Expand All @@ -92,6 +115,8 @@ tasks.clean {

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.

</details>

## Custom validation files directory

It is possible to customize the path where validation files are stored, in order to do that:
Expand All @@ -100,6 +125,8 @@ 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`)

The [Gradle plugin][gradle_validation_files_plugin] does not support a custom directory yet and expects the validation files below `data/test`.

## Normalization

Validation files only work with deterministic output (see also our [stance on determinism](https://github.com/cronn#determinism)).
Expand Down Expand Up @@ -170,9 +197,12 @@ assertWithFile(table.toString(), FileExtensions.MD);
## See also

* [IntelliJ plugin for validation file comparison][intellij_plugin]
* [Gradle plugin for validation files][gradle_validation_files_plugin]
* [File snapshots for Playwright and Vitest][frontend_file_snapshots]

[meld]: https://meldmerge.org/
[gradle_validation_files_plugin]: https://github.com/cronn/gradle-validation-files-plugin
[gradle_validation_files_plugin_portal]: https://plugins.gradle.org/plugin/de.cronn.validation-files
[intellij_plugin]: https://plugins.jetbrains.com/plugin/12931-validation-file-comparison
[assertj_soft_assertions]: https://assertj.github.io/doc/#assertj-core-soft-assertions
[frontend_file_snapshots]: https://github.com/cronn/file-snapshots
2 changes: 1 addition & 1 deletion build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ plugins {
`java-library`
`maven-publish`
signing
id("com.diffplug.spotless") version "latest.release"
id("com.diffplug.spotless") version "8.11.0"
id("org.jreleaser") version "1.26.0"
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,10 @@ default void assertWithFile(
String actualOutput, String filename, ValidationNormalizer normalizer) {
FailedAssertionHandler failedAssertionsCollector = failedAssertionHandler();
if (failedAssertionsCollector != null) {
failedAssertionsCollector.executeAndHandleFailedAssertion(
() -> {
FileBasedComparisonUtils.compareActualWithFileHidden(
actualOutput, filename, normalizer);
return null;
});
failedAssertionsCollector.executeAndHandleFailedAssertion(() -> {
FileBasedComparisonUtils.compareActualWithFileHidden(actualOutput, filename, normalizer);
return null;
});
} else {
FileBasedComparisonUtils.compareActualWithFileHidden(actualOutput, filename, normalizer);
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ public ValidationNormalizer build() {
/**
* @deprecated use withStringValue instead
*/
@Deprecated()
@Deprecated
public JsonReplacerBuilder withValue(String value) {
this.valueToReplace = "\"" + value + "\"";
return this;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -124,16 +124,15 @@ void testNormalizeIsThreadSafe() throws Exception {
String input = inputs[i % 2];
String expected = expectedOutputs[i % 2];
futures.add(
executor.submit(
() -> {
startLatch.await();
for (int j = 0; j < 500; j++) {
if (!expected.equals(dateTimeReplacer.normalize(input))) {
return false;
}
}
return true;
}));
executor.submit(() -> {
startLatch.await();
for (int j = 0; j < 500; j++) {
if (!expected.equals(dateTimeReplacer.normalize(input))) {
return false;
}
}
return true;
}));
}

startLatch.countDown();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,10 +54,9 @@ void testActualOutputHasChanged_throwsError() throws Throwable {

// When
Throwable error =
catchThrowable(
() ->
FileBasedComparisonUtils.compareActualWithFileHidden(
"text\nextra line", "file.txt", null));
catchThrowable(() ->
FileBasedComparisonUtils.compareActualWithFileHidden(
"text\nextra line", "file.txt", null));

// Then
assertThat(error)
Expand All @@ -75,20 +74,18 @@ void testActualOutputHasChanged_throwsError() throws Throwable {
void testCopyingOutputFileToValidationPath_fixesError() throws Throwable {
// Given
createPrefilledValidationFile("text", "file.txt");
assertThatThrownBy(
() ->
FileBasedComparisonUtils.compareActualWithFileHidden(
"text\nextra line", "file.txt", null))
assertThatThrownBy(() ->
FileBasedComparisonUtils.compareActualWithFileHidden(
"text\nextra line", "file.txt", null))
.isInstanceOf(FileBasedComparisonFailure.class);

// When
helper.copyOutputToValidation("file.txt");

// Then
assertThatCode(
() ->
FileBasedComparisonUtils.compareActualWithFileHidden(
"text\nextra line", "file.txt", null))
assertThatCode(() ->
FileBasedComparisonUtils.compareActualWithFileHidden(
"text\nextra line", "file.txt", null))
.doesNotThrowAnyException();
assertThat(helper.linesDiffOutputValidation("file.txt")).isEmpty();
}
Expand Down
Loading