browser: page element change matcher (#1562)

Author: MykolaGolubyev

webtau-browser/src/main/java/org/testingisdocumenting/webtau/browser/page/PageElement.java

@@ -42,10 +42,7 @@
 import org.testingisdocumenting.webtau.expectation.ActualPathAndDescriptionAware;
 import org.testingisdocumenting.webtau.expectation.ActualValueExpectations;
 import org.testingisdocumenting.webtau.expectation.state.VisibleStateAware;
-import org.testingisdocumenting.webtau.reporter.StepReportOptions;
-import org.testingisdocumenting.webtau.reporter.TokenizedMessage;
-import org.testingisdocumenting.webtau.reporter.WebTauStepInput;
-import org.testingisdocumenting.webtau.reporter.WebTauStepInputKeyValue;
+import org.testingisdocumenting.webtau.reporter.*;
 
 import java.util.*;
 import java.util.function.Consumer;
@@ -367,6 +364,23 @@ public void prettyPrint(PrettyPrinter printer) {
         new PageElementPrettyPrinter(this, 10).prettyPrint(printer);
     }
 
+    @Override
+    public void takeSnapshot() {
+        execute(tokenizedMessage().action("taking value snapshot").add(pathDescription),
+                () -> tokenizedMessage().action("value snapshot is taken").forP().add(pathDescription),
+                () -> snapshotValue.take(extractActualValue()));
+    }
+
+    @Override
+    public Object snapshotValue() {
+        return snapshotValue.required();
+    }
+
+    @Override
+    public Object currentValue() {
+        return extractActualValue();
+    }
+
     List<HtmlNode> extractHtmlNodes() {
         return extractHtmlNodes(findElements());
     }
@@ -574,21 +588,6 @@ private void checkNotNullAndExecuteScriptOnElement(String actionLabel, String sc
         ((JavascriptExecutor) driver).executeScript(script, argsList.toArray(new Object[0]));
     }
 
-    @Override
-    public void takeSnapshot() {
-        snapshotValue.take(extractActualValue());
-    }
-
-    @Override
-    public Object snapshotValue() {
-        return snapshotValue.required();
-    }
-
-    @Override
-    public Object currentValue() {
-        return extractActualValue();
-    }
-
     private Object extractActualValue() {
         return isMarkedAsAll ?
                 valuesList.get() :

webtau-docs/znai/browser/asynchronous-page.md

@@ -28,6 +28,13 @@ If presence/absence of an element is not important, you can directly to wait for
 
 Note: any matcher that you can use with `should` and `shouldNot` can be used with `waitTo` and `waitToNot`
 
+# Wait to change
+
+Use `change` matcher when you want to wait for any change of a value without knowing the specifics.
+
+:include-file: doc-artifacts/snippets/matchers/snapshotAndChange.groovy {title: "wait for change", noGap: true, noGapSeparator: true}
+:include-cli-output: doc-artifacts/matchers.groovy-console-output.txt {startLine: "change matcher", endLine: "change matcher", excludeStartEnd: true}
+
 # Wait on url
 
 Another cue to use could be a url change after an action.

webtau-docs/znai/browser/matchers.md

@@ -1,9 +1,7 @@
----
-type: two-sides
----
-
 # Text
 
+:include-xml: doc-artifacts/snippets/matchers/texts.html 
+
 :include-file: doc-artifacts/snippets/matchers/equalText.groovy {title: "exact text"}
 
 :include-file: doc-artifacts/snippets/matchers/equalTextRegexp.groovy {title: "regexp text"}
@@ -19,10 +17,10 @@ It is not required when you do an explicit comparison with the list on the right
 
 :include-file: doc-artifacts/snippets/matchers/equalListOfTextAndRegexp.groovy {title: "list of text and regexp"}
 
-:include-xml: doc-artifacts/snippets/matchers/texts.html {rightSide: true}
-
 # Numbers
 
+:include-xml: doc-artifacts/snippets/matchers/numbers.html
+
 :include-file: doc-artifacts/snippets/matchers/equalNumber.groovy {title: "exact number"}
 
 :include-file: doc-artifacts/snippets/matchers/greaterNumber.groovy {title: "greater than"}
@@ -33,13 +31,17 @@ It is not required when you do an explicit comparison with the list on the right
 
 :include-file: doc-artifacts/snippets/matchers/lessEqualListMixOfNumbers.groovy {title: "list of exact and greater/less"}
 
-:include-xml: doc-artifacts/snippets/matchers/numbers.html {rightSide: true}
-
 # State
 
+:include-file: doc-artifacts/snippets/matchers/state.html 
+
 :include-file: doc-artifacts/snippets/matchers/enabledDisabled.groovy {title: "enabled/disabled"}
 
 :include-file: doc-artifacts/snippets/matchers/visibleHidden.groovy {title: "visible/hidden"}
 
-:include-file: doc-artifacts/snippets/matchers/state.html {rightSide: true}
+# Snapshot And Change
+
+:include-file: doc-artifacts/snippets/matchers/snapshotAndChange.groovy {title: "wait for change", noGap: true, noGapSeparator: true}
+:include-cli-output: doc-artifacts/matchers.groovy-console-output.txt {startLine: "change matcher", endLine: "change matcher", excludeStartEnd: true}
+
 

webtau-docs/znai/release-notes/2.4/add-2024-01-10-browser-wait-for-change.md

@@ -0,0 +1 @@
+* Add: Browser page element [wait to change](browser/asynchronous-page#wait-to-change)

webtau-feature-testing/examples/scenarios/ui/matchers.groovy

@@ -71,4 +71,14 @@ scenario("visible state") {
     def feedback = $("#feedback")
     feedback.shouldBe hidden
     feedback.shouldNotBe visible
+}
+
+scenario("change matcher") {
+    def number = $("#number-to-change")
+    def trigger = $("#change-number")
+
+    number.takeSnapshot()
+    trigger.click()
+
+    number.waitTo change
 }

webtau-feature-testing/src/test/groovy/org/testingisdocumenting/webtau/featuretesting/WebTauBrowserFeaturesTestBase.groovy

@@ -220,6 +220,7 @@ class WebTauBrowserFeaturesTestBase {
                 "lessEqualListMixOfNumbers.groovy": "less equal list mix of numbers",
                 "enabledDisabled.groovy": "enable state",
                 "visibleHidden.groovy": "visible state",
+                "snapshotAndChange.groovy": "change matcher",
         ])
 
         extractHtmlSnippets(root, "matchers.html", [

webtau-feature-testing/src/test/resources/matchers.html

@@ -1,4 +1,5 @@
 <!--
+  ~ Copyright 2024 webtau maintainers
   ~ Copyright 2019 TWO SIGMA OPEN SOURCE, LLC
   ~
   ~ Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,6 +16,17 @@
   -->
 
 <html>
+<head>
+    <script>
+        function changeNumber() {
+            var htmlElement = document.getElementById('number-to-change');
+            var number = Number(htmlElement.innerText);
+            number++;
+            htmlElement.innerText = "" + number;
+        }
+    </script>
+    <title>webtau matchers test</title>
+</head>
 <body>
 <div id="numbers">
     <div>
@@ -46,5 +58,11 @@
         <div id="feedback" style="display: none;"></div>
     </div>
 </div>
+<div id="change">
+    <div>
+        <button id="change-number" onclick='changeNumber()'>Click to change number</button>
+        <div id="number-to-change">300</div>
+    </div>
+</div>
 </body>
 </html>

webtau-feature-testing/test-expectations/scenarios/ui/matchers/chrome-run-details.json

@@ -89,6 +89,12 @@
     "stepsSummary" : {
       "numberOfSuccessful" : 2
     }
+  }, {
+    "scenario" : "change matcher",
+    "shortContainerId" : "matchers.groovy",
+    "stepsSummary" : {
+      "numberOfSuccessful" : 3
+    }
   } ],
   "exitCode" : 0
 }

webtau-feature-testing/test-expectations/scenarios/ui/matchers/firefox-run-details.json

@@ -89,6 +89,12 @@
     "stepsSummary" : {
       "numberOfSuccessful" : 2
     }
+  }, {
+    "scenario" : "change matcher",
+    "shortContainerId" : "matchers.groovy",
+    "stepsSummary" : {
+      "numberOfSuccessful" : 3
+    }
   } ],
   "exitCode" : 0
 }