matchers: intro docs refersh (#1555)

Author: MykolaGolubyev

webtau-core-groovy/src/test/groovy/org/testingisdocumenting/webtau/MatchersGroovyTest.groovy

@@ -43,17 +43,32 @@ class MatchersGroovyTest {
         // string-string-example
     }
 
+    @Test
+    void "string negative comparison example"() {
+        // string-string-negative-example
+        def errorMessage = generateErrorMessage()
+        errorMessage.shouldNot == "completed"
+        // string-string-negative-example
+    }
+
     @Test
     void "string wait example"() {
         // wait-consume-message
-        actual(liveValue(this.&consumeMessage)).waitTo == "message we wait for"
+        actual(liveValue(this::consumeMessage)).waitTo == "message we wait for"
         // wait-consume-message
     }
 
+    @Test
+    void "string wait negative example"() {
+        // wait-negative-consume-message
+        actual(liveValue(this::consumeMessage)).waitToNot == "duplicate"
+        // wait-negative-consume-message
+    }
+
     @Test
     void "number wait example"() {
         // wait-number-records
-        actual(liveValue(this.&countRecords)).waitToBe >= 5
+        actual(liveValue(this::countRecords)).waitToBe >= 5
         // wait-number-records
     }
 
@@ -179,17 +194,21 @@ class MatchersGroovyTest {
 
     @Test
     void "any of matcher example"() {
+        // any-of-matcher-standalone
         def dateAsText = "2018-06-10"
         dateAsText.should == anyOf("2018-06-11", LocalDate.of(2018, 6, 10))
+        // any-of-matcher-standalone
     }
 
     @Test
     void "any of matcher with other matcher example"() {
+        // any-of-matcher-combo
         def dateAsText = "2018-06-10"
         dateAsText.should == anyOf("2018-06-11", greaterThan(LocalDate.of(2018, 1, 1)))
 
         def message = "hello world"
         message.shouldNot == anyOf("hello", contain("super"))
+        // any-of-matcher-combo
     }
 
     @Test

webtau-core/src/test/java/org/testingisdocumenting/webtau/MatchersTest.java

@@ -52,6 +52,16 @@ public void stringComparisonExample() {
         });
     }
 
+    @Test
+    public void stringNegativeComparisonExample() {
+        doc.console.capture("string-string-negative-comparison", () -> {
+            // string-string-negative-example
+            String errorMessage = generateErrorMessage();
+            actual(errorMessage).shouldNot(equal("completed"));
+            // string-string-negative-example
+        });
+    }
+
     @Test
     public void stringWaitExample() {
         doc.console.capture("wait-message", () -> {
@@ -61,6 +71,15 @@ public void stringWaitExample() {
         });
     }
 
+    @Test
+    public void stringWaitNegativeExample() {
+        doc.console.capture("wait-negative-message", () -> {
+            // wait-negative-consume-message
+            actual(liveValue(this::consumeMessage)).waitToNot(equal("duplicate"));
+            // wait-negative-consume-message
+        });
+    }
+
     @Test
     public void numberWaitExample() {
         // wait-number-records

webtau-docs/znai/matchers/any-of.md

@@ -5,9 +5,8 @@ Use `anyOf` matcher to match an expected value against any of the provided value
 
 ```tabs
 Groovy: 
-:include-groovy: org/testingisdocumenting/webtau/MatchersGroovyTest.groovy {
-    entry: "any of matcher example",
-    bodyOnly: true
+:include-file: org/testingisdocumenting/webtau/MatchersGroovyTest.groovy {
+    surroundedBy: "any-of-matcher-standalone"
 }
 :include-markdown: import-ref.md
 
@@ -25,16 +24,13 @@ You can mix values and other matchers passed to `anyOf`
 
 ```tabs
 Groovy: 
-:include-groovy: org/testingisdocumenting/webtau/MatchersGroovyTest.groovy {
-    entry: "any of matcher with other matcher example",
-    bodyOnly: true
+:include-file: org/testingisdocumenting/webtau/MatchersGroovyTest.groovy {
+    surroundedBy: "any-of-matcher-combo"
 }
 
 Java: 
 :include-java: org/testingisdocumenting/webtau/MatchersTest.java {
     entry: "anyOfMatcherWithOtherMatcherExample",
     bodyOnly: true
 } 
-```
-
-:include-markdown: static-import.md
+```

webtau-docs/znai/matchers/any-value.md

@@ -19,6 +19,4 @@ Java:
 
 :include-cli-output: doc-artifacts/any-value-table-output.txt {
   title: "console output"
-}
-
-:include-markdown: static-import.md
+}

webtau-docs/znai/matchers/contain-exactly.md

@@ -9,10 +9,12 @@ Groovy:
 :include-file: org/testingisdocumenting/webtau/expectation/contain/ContainExactlyMatcherGroovyTest.groovy {
   surroundedBy: "possible-mismatches-example"
 }
+:include-markdown: import-ref.md
 Java:
 :include-file: org/testingisdocumenting/webtau/expectation/contain/ContainExactlyMatcherJavaTest.java {
   surroundedBy: "possible-mismatches-example"
 }
+:include-markdown: import-ref.md
 ```
 
 Console output displays potential mismatches to help with investigation:

webtau-docs/znai/matchers/import-and-dependencies.md

@@ -2,7 +2,7 @@
 
 # Matchers Specific Import
 
-To specifically import `matchers` only use
+To specifically import `matchers` only use:
 
 ```tabs
 Groovy:
@@ -14,3 +14,16 @@ Java:
 :include-file: org/testingisdocumenting/webtau/expectation/equality/handlers/StringMatchersJavaExamplesTest.java {title: "matchers import", include: "Matchers.*"} 
 :include-file: maven/core-dep.xml {title: "maven dependency"}
 ```
+
+# Core Module Import
+
+To have one import for `matchers` and utilities like `list`, `map`, `table` use:
+
+```tabs
+Groovy:
+:include-file: org/testingisdocumenting/webtau/MatchersTest.java { include: "WebTauCore.*", replace: [";", ""] }
+
+Java:
+:include-file: org/testingisdocumenting/webtau/MatchersTest.java { include: "WebTauCore.*" }
+```
+

webtau-docs/znai/matchers/introduction.md

@@ -1,7 +1,7 @@
-WebTau provides two methods to assert values: `should` and `waitTo`. They work for business logic testing, HTTP, Browser, and other layers.
+WebTau provides two ways to assert values: `should` and `waitTo`. They work for business logic testing, HTTP, Browser, and other layers.
 Methods accept a matcher as a second parameter:
 
-WebTau provides console output of all the matches it does, regardless of whether it fails or passes.
+WebTau provides console output for all the matching it does, regardless of whether it fails or passes.
 
 # Should 
 
@@ -15,7 +15,6 @@ Groovy:
     surroundedBy: "string-string-example",
     commentsType: "remove"
 }
-
  Note: Groovy has a shortcut for `equal` matcher.
 
 :include-markdown: import-ref.md
@@ -85,6 +84,46 @@ Java:
 } 
 ``` 
 
+# Negative Matching
+
+Both `should` and `waitTo` have negative forms:
+
+```tabs
+Groovy: 
+:include-file: org/testingisdocumenting/webtau/MatchersGroovyTest.groovy {
+    title: "shouldNot example",
+    surroundedBy: "string-string-negative-example",
+    noGap: true
+}
+:include-cli-output: doc-artifacts/string-string-negative-comparison.txt 
+
+Java: 
+:include-file: org/testingisdocumenting/webtau/MatchersTest.java {
+    title: "shouldNot example",
+    surroundedBy: "string-string-negative-example",
+    noGap: true
+} 
+:include-cli-output: doc-artifacts/string-string-negative-comparison.txt 
+``` 
+
+```tabs
+Groovy: 
+:include-file: org/testingisdocumenting/webtau/MatchersGroovyTest.groovy {
+    title: "waitToNot example",
+    surroundedBy: "wait-negative-consume-message",
+    noGap: true
+}
+:include-cli-output: doc-artifacts/wait-negative-message.txt 
+
+Java: 
+:include-file: org/testingisdocumenting/webtau/MatchersTest.java {
+    title: "waitToNot example",
+    surroundedBy: "wait-negative-consume-message",
+    noGap: true
+} 
+:include-cli-output: doc-artifacts/wait-negative-message.txt 
+``` 
+
 # Failure Output
 
 Above you saw how WebTau outputs matched information.
@@ -95,16 +134,16 @@ In case of failed assertion WebTau outputs additional information about the actu
 Groovy: 
 :include-file: org/testingisdocumenting/webtau/MatchersGroovyTest.groovy {
     title: "assertion",
-    surroundedBy: "failed-list"
+    surroundedBy: "failed-list",
+    noGap: true
 }
+:include-cli-output: doc-artifacts/list-failure.txt 
 
 Java: 
 :include-file: org/testingisdocumenting/webtau/MatchersTest.java {
     title: "assertion",
-    surroundedBy: "failed-list"
+    surroundedBy: "failed-list",
+    noGap: true
 } 
+:include-cli-output: doc-artifacts/list-failure.txt 
 ``` 
-
-:include-cli-output: doc-artifacts/list-failure.txt {title: "failed assertion console output"}
-
-:include-markdown: static-import.md

webtau-docs/znai/matchers/java-beans-and-records.md

@@ -91,8 +91,6 @@ Java:
 
 :include-cli-output: doc-artifacts/beans-table-contain-output.txt {title: "contain handler output"}
 
-:include-markdown: static-import.md
-
 # Java Records 
 
 WebTau compares Java Records with maps and tables in the same way as Java Beans.

webtau-docs/znai/matchers/static-import.md

@@ -75,5 +75,3 @@ Java:
 }
  ``` 
 
-:include-markdown: static-import.md
-