Merge pull request #10888 from murdos/improve-approval-testing

Approval testing module improvements

src/main/java/tech/jhipster/lite/generator/server/javatool/approvaltesting/domain/ApprovalTestingModuleFactory.java

@@ -3,20 +3,30 @@
 import static tech.jhipster.lite.module.domain.JHipsterModule.*;
 
 import tech.jhipster.lite.module.domain.JHipsterModule;
+import tech.jhipster.lite.module.domain.file.JHipsterDestination;
+import tech.jhipster.lite.module.domain.file.JHipsterSource;
 import tech.jhipster.lite.module.domain.properties.JHipsterModuleProperties;
 import tech.jhipster.lite.shared.error.domain.Assert;
 
 public class ApprovalTestingModuleFactory {
 
+  private static final JHipsterSource SOURCE = from("server/javatool/approvaltesting");
+
   public JHipsterModule build(JHipsterModuleProperties properties) {
     Assert.notNull("properties", properties);
 
+    String packagePath = properties.packagePath();
+    JHipsterDestination testDestination = toSrcTestJava().append(packagePath);
+
     //@formatter:off
     return moduleBuilder(properties)
-      .documentation(documentationTitle("Approval Testing"),from("server/javatool/approvaltesting/approval-testing.md"))
+      .documentation(documentationTitle("Approval Testing"), SOURCE.append("approval-testing.md"))
       .javaDependencies()
         .addTestDependency(groupId("com.approvaltests"), artifactId("approvaltests"), versionSlug("approvaltests"))
         .and()
+      .files()
+        .add(SOURCE.append("test").template("PackageSettings.java"), testDestination.append("PackageSettings.java"))
+        .and()
       .build();
     //@formatter:on
   }

src/main/resources/generator/server/javatool/approvaltesting/approval-testing.md

@@ -2,17 +2,19 @@
 
 Instead of writing individual assertions, ApprovalTests focuses on verifying the overall output. This is particularly useful when testing complex objects, files, or outputs where writing assertions would be tedious.
 
-Here is the example of approval-based tests from [ApprovalTests.java User Guide](https://github.com/approvals/ApprovalTests.Java/blob/master/README.md)
+## Basic Example
+
+Here is an example of approval-based tests from [ApprovalTests.java User Guide](https://github.com/approvals/ApprovalTests.Java/blob/master/README.md)
 
 ```java
 import java.util.Arrays;
 import org.approvaltests.Approvals;
 import org.junit.jupiter.api.Test;
 
-public class SampleArrayTest {
+class SampleArrayTest {
 
   @Test
-  public void testList() {
+  void verifyArraySorting() {
     String[] names = { "Llewellyn", "James", "Dan", "Jason", "Katrina" };
     Arrays.sort(names);
     Approvals.verifyAll("", names);
@@ -21,6 +23,58 @@ public class SampleArrayTest {
 
 ```
 
-This will a File `SampleArrayTest.testList.received.txt`
+This will produce a file `SampleArrayTest.verifyArraySorting.received.txt`:
+
+```
+[0] = Dan
+[1] = James
+[2] = Jason
+[3] = Katrina
+[4] = Llewellyn
+```
+
+Simply rename this to `SampleTest.verifyArraySorting.approved.txt` and the test will now pass.
+The `*.approved.*` files should be committed to source control, and updated whenever the inputs or the logic of the test change.
+
+## Usage with Parameterized Tests
+
+By default, ApprovalTests generates one file per test.
+For @ParameterizedTests, we want to generate multiple files for a single parameterized test, where each filename includes the test parameters.
+
+```java
+@ParameterizedTest
+@ValueSource(strings = { "parameter1", "parameter2" })
+void sampleParameterizedTest(String parameter) {
+  Object output = // ... your code goes here
+    Approvals.verify(output, Approvals.NAMES.withParameters(parameter));
+}
+
+```
 
-Simply rename this to `SampleTest.testList.approved.txt` and the test will now pass.
+This will generate files `sampleParameterizedTest.parameter1.approved.txt` and `sampleParameterizedTest.parameter2.approved.txt`.
+
+## Test Combinations
+
+ApprovalTests supports test combinations, where multiple parameters are used to generate a single file.
+See [ApprovalTests.java User Guide](https://github.com/approvals/ApprovalTests.Java/blob/master/approvaltests/docs/README.md#test-combinations) for more details.
+
+```java
+@Test
+void sampleCombinationCheck(String parameter) {
+  String[] strings = { "hello", "world" };
+  Integer[] numbers = { 1, 2, 3 };
+  CombinationApprovals.verifyAllCombinations((string, number) -> "(%s %s)".formatted(string, number), strings, numbers);
+}
+
+```
+
+The approved `sampleCombinationCheck.approved.txt` file will contain:
+
+```
+[hello, 1] => (hello 1)
+[hello, 2] => (hello 2)
+[hello, 3] => (hello 3)
+[world, 1] => (world 1)
+[world, 2] => (world 2)
+[world, 3] => (world 3)
+```

src/main/resources/generator/server/javatool/approvaltesting/test/PackageSettings.java.mustache

@@ -0,0 +1,18 @@
+package {{packageName}};
+
+import org.approvaltests.core.ApprovalFailureReporter;
+import org.approvaltests.reporters.AutoApproveWhenEmptyReporter;
+import org.approvaltests.reporters.DiffReporter;
+import org.approvaltests.reporters.FirstWorkingReporter;
+
+/**
+ * ApprovalTests.Java configuration.
+ * */
+public class PackageSettings {
+
+  private static final String ApprovalBaseDirectory = "../resources";
+  private static final ApprovalFailureReporter UseReporter = new FirstWorkingReporter(
+    new AutoApproveWhenEmptyReporter(),
+    new DiffReporter()
+  );
+}

src/test/java/tech/jhipster/lite/generator/server/javatool/approvaltesting/domain/ApprovalTestingModuleFactoryTest.java

@@ -1,7 +1,8 @@
 package tech.jhipster.lite.generator.server.javatool.approvaltesting.domain;
 
-import static tech.jhipster.lite.TestFileUtils.*;
-import static tech.jhipster.lite.module.infrastructure.secondary.JHipsterModulesAssertions.*;
+import static tech.jhipster.lite.TestFileUtils.tmpDirForTest;
+import static tech.jhipster.lite.module.infrastructure.secondary.JHipsterModulesAssertions.assertThatModuleWithFiles;
+import static tech.jhipster.lite.module.infrastructure.secondary.JHipsterModulesAssertions.pomFile;
 
 import org.junit.jupiter.api.Test;
 import tech.jhipster.lite.UnitTest;
@@ -21,7 +22,7 @@ void shouldBuildApprovalTestsModule() {
     JHipsterModule module = factory.build(properties);
 
     assertThatModuleWithFiles(module, pomFile())
-      .hasFiles("documentation/approval-testing.md")
+      .hasFiles("documentation/approval-testing.md", "src/test/java/com/mycompany/myapp/PackageSettings.java")
       .hasFile("pom.xml")
       .containing(
         """