cache: cache.value + docs (#806)

Author: MykolaGolubyev

webtau-cache/src/main/java/org/testingisdocumenting/webtau/cache/Cache.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright 2021 webtau maintainers
  * Copyright 2019 TWO SIGMA OPEN SOURCE, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,6 +18,12 @@
 package org.testingisdocumenting.webtau.cache;
 
 import org.testingisdocumenting.webtau.cfg.WebTauConfig;
+import org.testingisdocumenting.webtau.reporter.StepReportOptions;
+import org.testingisdocumenting.webtau.reporter.WebTauStep;
+
+import static org.testingisdocumenting.webtau.reporter.IntegrationTestsMessageBuilder.*;
+import static org.testingisdocumenting.webtau.reporter.IntegrationTestsMessageBuilder.stringValue;
+import static org.testingisdocumenting.webtau.reporter.TokenizedMessage.tokenizedMessage;
 
 public class Cache {
     public static final Cache cache = new Cache();
@@ -27,15 +34,29 @@ private Cache() {
         fileBasedCache = new FileBasedCache(() -> WebTauConfig.getCfg().getCachePath());
     }
 
+    public <E> CachedValue<E> value(String id) {
+        return new CachedValue<>(cache, id);
+    }
+
     public <E> E get(String key) {
-        return fileBasedCache.get(key);
+        WebTauStep step = WebTauStep.createStep(null,
+                tokenizedMessage(action("getting cached value"), FROM, id(key)),
+                (r) -> tokenizedMessage(action("got cached value"), FROM, id(key), COLON, stringValue(r)),
+                () -> fileBasedCache.get(key));
+
+        return step.execute(StepReportOptions.SKIP_START);
     }
 
     public void put(String key, Object value, long expirationTime) {
-        fileBasedCache.put(key, value, expirationTime);
+        WebTauStep step = WebTauStep.createStep(null,
+                tokenizedMessage(action("caching value"), AS, id(key), COLON, stringValue(value)),
+                () -> tokenizedMessage(action("cached value"), AS, id(key), COLON, stringValue(value)),
+                () -> fileBasedCache.put(key, value, expirationTime));
+
+        step.execute(StepReportOptions.SKIP_START);
     }
 
     public void put(String key, Object value) {
-        fileBasedCache.put(key, value);
+        put(key, value, Long.MAX_VALUE);
     }
 }

webtau-cache/src/main/java/org/testingisdocumenting/webtau/cache/CachedValue.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2021 webtau maintainers
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.testingisdocumenting.webtau.cache;
+
+public class CachedValue<E> {
+    private final Cache cache;
+    private final String id;
+
+    public CachedValue(Cache cache, String id) {
+        this.cache = cache;
+        this.id = id;
+    }
+
+    public E get() {
+        return cache.get(id);
+    }
+
+    public void set(E value) {
+        cache.put(id, value);
+    }
+}

webtau-cache/src/main/java/org/testingisdocumenting/webtau/cache/FileBasedCache.java

@@ -30,7 +30,7 @@
 import java.util.concurrent.atomic.AtomicLong;
 import java.util.function.Supplier;
 
-public class FileBasedCache {
+class FileBasedCache {
     private static final String VALUE_KEY = "value";
     private static final String EXPIRATION_TIME_KEY = "expirationTime";
 
@@ -81,7 +81,6 @@ public void put(String key, Object value, long expirationTime) {
 
     public void put(String key, Object value) {
         put(key, value, Long.MAX_VALUE);
-        flushCacheToDiskIfRequired();
     }
 
     private Map<String, Object> createValueWithMeta(Object value, long expirationTime) {

webtau-cache/src/test/groovy/org/testingisdocumenting/webtau/cache/FileBasedCacheTest.groovy

@@ -1,4 +1,5 @@
 /*
+ * Copyright 2021 webtau maintainers
  * Copyright 2019 TWO SIGMA OPEN SOURCE, LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -92,8 +93,8 @@ class FileBasedCacheTest {
     void "should create non expiring values if no expiration time is provided"() {
         def cacheFile = createTempCacheFile([:])
 
-        def fileBasedCache = new FileBasedCache({ -> cacheFile })
         Time.timeProvider = new DummyTimeProvider([0, 11_000])
+        def fileBasedCache = new FileBasedCache({ -> cacheFile })
         fileBasedCache.put('accessToken', 'abc')
 
         Assert.assertEquals(String.format('{%n' +

webtau-core/src/main/java/org/testingisdocumenting/webtau/reporter/IntegrationTestsMessageBuilder.java

@@ -67,6 +67,7 @@ public MessageToken token(Object value) {
     public static final MessageToken OF = TokenTypes.PREPOSITION.token("of");
     public static final MessageToken FOR = TokenTypes.PREPOSITION.token("for");
     public static final MessageToken FROM = TokenTypes.PREPOSITION.token("from");
+    public static final MessageToken AS = TokenTypes.PREPOSITION.token("as");
     public static final MessageToken USING = TokenTypes.PREPOSITION.token("using");
     public static final MessageToken INTO = TokenTypes.PREPOSITION.token("into");
     public static final MessageToken ON = TokenTypes.PREPOSITION.token("on");

webtau-docs/znai/toc

@@ -49,10 +49,14 @@ cli
     introduction
     foreground-command
     background-command
+REPL
+    experiments
+    test-runs
 utilities
     introduction
     data
     file-system
+    cache
 groovy-standalone-runner
     introduction
     data-driven-scenarios
@@ -62,9 +66,6 @@ groovy-standalone-runner
     test-metadata
     test-listeners
     test-execution
-REPL
-    experiments
-    test-runs
 configuration
     environments
     options

webtau-docs/znai/utilities/cache.md

@@ -0,0 +1,22 @@
+# Cached Value
+
+When you develop tests, you don't have to restart the whole flow from the beginning.
+
+Imagine you have a multi step test that includes running Command Line tool and then validating REST API response, and 
+then opening a browser to assert UI values.
+
+Cache long steps results like created entities `ids` to speed up tests development.
+
+In the example below, you create first scenario that runs a heavy command line tool that generates an id. 
+We then cache the value and you can write a second scenario and keep re-running it, without the need to re-run the first one.
+
+:include-file: scenarios/cache/cachedValue.groovy {
+  title: "cached value",
+  startLine: "example",
+  endLine: "example",
+  excludeStartEnd: true,
+  commentsType: "inline"
+}
+
+Note: Use [Selective Run](groovy-standalone-runner/selective-run) or [REPL mode](REPL/test-runs) 
+to run one scenario at a time.

webtau-docs/znai/utilities/introduction.md

@@ -2,4 +2,5 @@ Webtau has several modules to help you simplify automation processes. All operat
 detailed information on steps executed and details are included in web report as well as console output.
 
 * [data](utilities/data) - module to read structured data like CSV and JSON into data structures like `TableData`, lists and maps 
-* [file system](utilities/file-system) - module to create files, directories, reading data, unzipping, etc 
+* [file system](utilities/file-system) - module to create files, directories, reading data, unzipping, etc 
+* [cache](utilities/cache) - module to cache results of test steps to be able to skip them during test development and exploration 

webtau-feature-testing/examples/scenarios/cache/cachedValue.groovy

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2021 webtau maintainers
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package scenarios.cache
+
+// example
+import static org.testingisdocumenting.webtau.WebTauGroovyDsl.*
+
+def createdId = cache.value("cli-heavy-created-id") // declare cached value with distinct id
+
+scenario("heavy setup operation") {
+    def cliResult = cli.run("scripts/cli-heavy-process") // long running process that you don't want to re-run as you write your tests
+    createdId.set(cliResult.extractFromOutputByRegexp("id=(\\S+)")) // caching the extracted id from CLI run
+}
+
+scenario("using previous setup id even after restart") {
+    def id = createdId.get() // using cached value from previous test run. value will be preserved between restarts and re-compile
+    http.get("/resource/${id}") {
+        message.should == "hello"
+    }
+}
+// example

webtau-feature-testing/scripts/cli-heavy-process

@@ -0,0 +1,3 @@
+#!/bin/bash
+echo heavy process start
+echo id=generated-id-123