From 8e6e03bef88826138acd422193e8c16b2bf291d1 Mon Sep 17 00:00:00 2001
From: Tobias Stamann <tobias.staman@holisticon.de>
Date: Tue, 23 Jan 2024 16:36:06 +0100
Subject: [PATCH] Updated README.md

---
 README.md | 170 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 97 insertions(+), 73 deletions(-)

diff --git a/README.md b/README.md
index 52a5ba8..216daa4 100644
--- a/README.md
+++ b/README.md
@@ -34,13 +34,24 @@ Simply add the following dependencies to your project to be able to use this tes
 <dependencies>
 
    <!-- Compile testing framework -->
-       <dependency>
+   <dependency>
        <groupId>io.toolisticon.cute</groupId>
        <artifactId>cute</artifactId>
        <version>${currentVersion}</version>
        <scope>test</scope>
    </dependency>
-
+    
+   <!-- 
+        Legacy API : Only add it if you don't want to use the new API.
+                     or migration to new API isn't an option.
+    -->
+    <dependency>
+        <groupId>io.toolisticon.cute</groupId>
+        <artifactId>cute-legacy</artifactId>
+        <version>${currentVersion}</version>
+        <scope>test</scope>
+    </dependency>
+   
    <!-- 
        optional : only needed if you want to trigger assertion 
                   errors via your unit test framework
@@ -56,7 +67,7 @@ Simply add the following dependencies to your project to be able to use this tes
 </dependencies>
 ```
      
-# Tests types
+# Tests Types
 
 There are two types of tests: Unit tests and Compilation (or Integration) Tests.
 
@@ -70,39 +81,40 @@ For both test types you can test
 The CompileTestBuilder always returns immutable CompileTestBuilder instances. 
 So it's safe to initialize a base CompileTestBuilder instance once in a testclass and to refine it further in the testcases.
 
-## Compilation tests
+## Black-Box-Compilation tests
 
-Compilation test allow you to define testcase source files and to apply your processor on it.
+Black-Box-Compilation test allow you to define testcase source files and to apply your processor on it during its compilation.
 
 ```java
-@Test
-public void exampleCompilationTest() {
-
-   CompileTestBuilder.compilationTest()
-       .addSources("/exampletestcase/Testcase1.java")
-       .addProcessors(YourProcessorUnderTest.class)
-       .compilationShouldSucceed()
-       .expectWarningMessage()
+ Cute.blackBoxTest()
+    .given()
+        .processors(YourProcessorUnderTest.class)
+        .andSourceFiles("/exampletestcase/Testcase1.java")
+    .whenCompiled()
+    .thenExpectThat()
+        .compilationSucceeds()
+        .andThat()
+            .compilerMessage()
+            .ofKindWarning()
             .atSource("/exampletestcase/Testcase1.java")
-            .atLineNumber(10L)
-            .atColumnNumber(20L)
-            .thatContains("WARNING SNIPPET(will check if a warning exists that contains passed string)")
-       .expectThatGeneratedSourceFileExists(
-               "your.test.package.GeneratedFile",
-               JavaFileObjectUtils.readFromString("package your.test.package;\npublic class GeneratedFile{}"))
-       .executeTest();
-
-}
+            .atLine(10L)
+            .atColumn(20L)
+            .contains("WARNING SNIPPET(will check if a warning exists that contains passed string)")
+        .andThat()
+            .generatedSourceFile("your.test.package.GeneratedFile")
+            .matches(
+                CuteApi.ExpectedFileObjectMatcherKind.BINARY,
+                JavaFileObjectUtils.readFromString("package your.test.package;\npublic class GeneratedFile{}")
+            )
+        .executeTest();
 ```
 
 Additionally, to the explicitly configured assertions it implicitly checks if your annotation processor has been applied and triggers an AssertionError if not.
 
-
-
 ## Unit tests
 
 Usually - if you are developing annotation processors - your code is likely to rely on the tools provided to the annotation processor via the ProcessingEnvironment like Filer, Messager, Types and Elements.
-These classes and the Java compile time model are hard to mock. Thats why unit testing is usually very hard to do.
+These classes and the Java compile time model are hard to mock. That's why unit testing is usually very hard to do.
 This library helps you to execute unit test at compile time, giving you the ProcessingEnvironment's tools and access to the compile time model for free.
 
 The unit test concept provided by this library uses a default source file and applies a default annotation processor on it. 
@@ -115,24 +127,29 @@ Your unit test code can be declared via the fluent api:
 @Test
 public void exampleUnitTest() {
 
-    CompileTestBuilder.unitTest()
-        .defineTest(SampleProcesssor.class, new UnitTestForTestingAnnotationProcessors<SampleProcesssor,TypeElement>() {
+    Cute.unitTest()
+        .when()
+        .passInProcessor(SampleProcesssor.class)
+        .intoUnitTest( new UnitTestForTestingAnnotationProcessorsWithoutPassIn<SampleProcesssor>() {
             @Override
-            public void unitTest(SampleProcesssor unit, ProcessingEnvironment processingEnvironment, TypeElement typeElement) {
-
+            public void unitTest(SampleProcesssor unit, ProcessingEnvironment processingEnvironment) {
+            
                 // Processor's init() method was called by cute framework
                 String result = unit.yourMethodToTest("ABC");
-
+            
                 // AssertionErrors will be passed through your external unit test function
                 MatcherAssert.assertThat(result, Matchers.is("EXPECTED RESULT"));
-
+            
             }
         })
-        .compilationShouldSucceed()
-        .expectWarningMessage()
-            .thatContains("WARNING SNIPPET(will check if a warning exists that contains passed string)")
+        .thenExpectThat()
+            .compilationSucceeds()
+            .andThat()
+            .compilerMessage()
+                .ofKindWarning()
+                .contains("WARNING SNIPPET(will check if a warning exists that contains passed string)")
         .executeTest();
-    
+
 }
 ```
  
@@ -146,59 +163,66 @@ Another cute feature is that it's possible to easily pass in elements and even a
 For passing in elements all you need to do is to create a static class next to your unit tests and to add the _PassIn_ annotation on the element you want to pass in.
 The static class then can be used as parameter in _defineTestWithPassedInElement_ method.
 
-Additional you can pass in an annotation processor by using the annotation processor class  as a parameter in _defineTestWithPassedInElement_ method.
+Additionally, you can pass in an annotation processor by using the annotation processor class  as a parameter in _defineTestWithPassedInElement_ method.
 An instance of the annotation processor will be created and initialized.
 
 ```java
-    private static class PassedInElement {
-        // Add your custom code like
-        @PassIn
-        void yourMethodToBePassedIn(){
-        }   
+private static class PassedInElement {
+    // Add your custom code like
+    @PassIn
+    void yourMethodToBePassedIn(){
     }
-    
-    // Example 1 : Pass in element
-    @Test
-    public void yourUnitTestWithPassedInElement() {
+}
 
-        CompileTestBuilder
-                .unitTest()
-                .defineTestWithPassedInElement(PassedInElement.class, new UnitTest<ExecutableElement>() {
-                    @Override
-                    public void unitTest(ProcessingEnvironment processingEnvironment, ExecutableElement element) {
+    // Example 1 : Pass in element
+@Test
+public void yourUnitTestWithPassedInElement() {
 
-                        // put your unit test code
+    Cute
+        .unitTest()
+        .when().passInElement().<ExecutableElement>fromClass(PassedInElement.class)
+        .intoUnitTest( new UnitTest<ExecutableElement>() {
+            @Override
+            public void unitTest(ProcessingEnvironment processingEnvironment, ExecutableElement element) {
 
-                    }
-                })
-                .compilationShouldSucceed()
-                .executeTest();
+                // put your unit test code
+                // ....
 
+            }
+        })
+        .thenExpectThat()
+        .compilationSucceeds()
+        .executeTest();
 
-    }
 
-    // Example 2 : Pass in annotation processor and element
-    // The processor will be instantiated and initialized
-    @Test
-    public void yourUnitTestWithPassedInElementAndProcessor() {
+}
 
-        CompileTestBuilder
-                .unitTest()
-                .defineTestWithPassedInElement(YourProcessorToTest.class, PassedInElement.class, new UnitTestForTestingAnnotationProcessors<YourProcessorToTest, ExecutableElement>() {
-                    @Override
-                    public void unitTest(YourProcessorToTest unit, ProcessingEnvironment processingEnvironment, ExecutableElement element) {
+// Example 2 : Pass in annotation processor and element
+// The processor will be instantiated and initialized
+@Test
+public void yourUnitTestWithPassedInElementAndProcessor() {
+
+    Cute
+        .unitTest()
+        .when()
+        .passInProcessor(YourProcessorToTest.class)
+        .andPassInElement().<ExecutableElement>fromClass(PassedInElement.class)
+        .intoUnitTest( new UnitTestForTestingAnnotationProcessors<YourProcessorToTest, ExecutableElement>() {
+            @Override
+            public void unitTest(YourProcessorToTest unit, ProcessingEnvironment processingEnvironment, ExecutableElement element) {
 
-                        // put your unit test code
-                        String result = unit.methodToTest(element);
-                        MatcherAssert.assertThat(result, Matchers.is("EXPECTED RESULT"));
+                // put your unit test code
+                String result = unit.methodToTest(element);
+                MatcherAssert.assertThat(result, Matchers.is("EXPECTED RESULT"));
 
-                    }
-                })
-                .compilationShouldSucceed()
-                .executeTest();
+            }
+        })
+        .thenExpectThat()
+        .compilationSucceeds()
+        .executeTest();
 
 
-    }
+}
 ```
  
 # Projects using this toolkit library