documentation: utilities -> data (#780)

Author: MykolaGolubyev

webtau-data/src/main/java/org/testingisdocumenting/webtau/data/DataCsv.java

@@ -26,18 +26,46 @@
 import static org.testingisdocumenting.webtau.data.DataContentUtils.dataTextContent;
 
 public class DataCsv {
+    /**
+     * Use <code>data.csv.table</code> to read data as {@link TableData} from CSV file.
+     * Passed path is either relative based on working dir or absolute path. Or it can be a resource class path.
+     * @param fileOrResourcePath relative path, absolute path or classpath resource path
+     * @return table data with CSV content
+     */
     public TableData table(String fileOrResourcePath) {
         return tableFromListOfMaps(CsvUtils.parse(textContent(fileOrResourcePath)));
     }
 
+    /**
+     * Use <code>data.csv.tableAutoConverted</code> to read data as {@link TableData} from CSV file. Numeric values become values of Numeric type instead of String type.
+     * Passed path is either relative based on working dir or absolute path. Or it can be a resource class path.
+     *
+     * @param fileOrResourcePath relative path, absolute path or classpath resource path
+     * @return table data with CSV content
+     */
     public TableData tableAutoConverted(String fileOrResourcePath) {
         return tableFromListOfMaps(CsvUtils.parseWithAutoConversion(textContent(fileOrResourcePath)));
     }
 
+    /**
+     * Use <code>data.csv.listOfMaps</code> to read data as {@link java.util.List} of {@link java.util.Map} from CSV file.
+     * Passed path is either relative based on working dir or absolute path. Or it can be a resource class path.
+     *
+     * @param fileOrResourcePath relative path, absolute path or classpath resource path
+     * @return list of maps
+     */
     public List<Map<String, String>> listOfMaps(String fileOrResourcePath) {
         return CsvUtils.parse(textContent(fileOrResourcePath));
     }
 
+    /**
+     * Use <code>data.csv.listOfMaps</code> to read data as {@link java.util.List} of {@link java.util.Map} from CSV file.
+     * Numeric values become values of Numeric type instead of String type.
+     * Passed path is either relative based on working dir or absolute path. Or it can be a resource class path.
+     *
+     * @param fileOrResourcePath relative path, absolute path or classpath resource path
+     * @return list of maps
+     */
     public List<Map<String, Object>> listOfMapsAutoConverted(String fileOrResourcePath) {
         return CsvUtils.parseWithAutoConversion(textContent(fileOrResourcePath));
     }

webtau-data/src/main/java/org/testingisdocumenting/webtau/data/DataJson.java

@@ -24,10 +24,22 @@
 import static org.testingisdocumenting.webtau.data.DataContentUtils.dataTextContent;
 
 public class DataJson {
+    /**
+     * Use <code>data.json.map</code> to read data as {@link java.util.Map} from JSON file.
+     * Passed path is either relative based on working dir or absolute path. Or it can be a resource class path.
+     * @param fileOrResourcePath relative path, absolute path or classpath resource path
+     * @return list of primitive values or maps/list
+     */
     public Map<String, ?> map(String fileOrResourcePath) {
         return JsonUtils.deserializeAsMap(textContent(fileOrResourcePath));
     }
 
+    /**
+     * Use <code>data.json.list</code> to read data as {@link java.util.List} from JSON file.
+     * Passed path is either relative based on working dir or absolute path. Or it can be a resource class path.
+     * @param fileOrResourcePath relative path, absolute path or classpath resource path
+     * @return list of primitive values or maps/list
+     */
     public List<?> list(String fileOrResourcePath) {
         return JsonUtils.deserializeAsList(textContent(fileOrResourcePath));
     }

webtau-docs/znai/groovy-standalone-runner/data-driven-scenarios.md

@@ -7,7 +7,7 @@ Define scenarios in a loop to have dynamic scenarios based on provided data.
 
 # CSV 
 
-Use `data.csv` to conveniently build your scenarios from an external `CSV` data set.
+Use [data.csv](utilities/data#csv) to conveniently build your scenarios from an external `CSV` data set.
 
 :include-file: examples/use-cases.csv {title: "examples/use-cases.csv"}
 

webtau-docs/znai/lookup-paths

@@ -36,6 +36,7 @@
 ../../webtau-db/src/test/groovy
 ../../webtau-db/target/test-classes
 ../../webtau-db/src/test
+../../webtau-data/src/main/java
 ../../webtau-cli-testing/src/test/groovy
 ../../webtau-cli-testing/target/doc-artifacts
 ../target/classes

webtau-docs/znai/references.csv

@@ -0,0 +1,3 @@
+TableData,reference/table-data
+java.util.List,https://docs.oracle.com/javase/8/docs/api/java/util/List.html
+java.util.Map,https://docs.oracle.com/javase/8/docs/api/java/util/Map.html

webtau-docs/znai/toc

@@ -49,6 +49,9 @@ cli
     introduction
     foreground-command
     background-command
+utilities
+    introduction
+    data
 groovy-standalone-runner
     introduction
     data-driven-scenarios

webtau-docs/znai/utilities/data.md

@@ -0,0 +1,48 @@
+# CSV
+
+## Table Data 
+
+:include-java-doc: org/testingisdocumenting/webtau/data/DataCsv.java {entry: "table"}
+
+:include-table: examples/data/table.csv {title: "data/table.csv"}
+
+:include-file: doc-artifacts/snippets/readingData/csvTable.groovy {title: "read table data from csv"}
+
+Note: by default numeric values are read as strings, to auto convert numeric values to actual numbers use `tableAutoConverted` method
+
+:include-java-doc: org/testingisdocumenting/webtau/data/DataCsv.java {entry: "tableAutoConverted"}
+
+:include-file: doc-artifacts/snippets/readingData/csvTableAutoConverted.groovy {title: "read table data from csv with auto conversion"}
+
+## List Of Map
+
+:include-table: examples/data/table.csv {title: "data/table.csv"}
+
+:include-java-doc: org/testingisdocumenting/webtau/data/DataCsv.java {entry: "listOfMaps"}
+
+:include-file: doc-artifacts/snippets/readingData/listOfMaps.groovy {title: "read list of maps from csv"}
+
+Note: by default numeric values are read as strings, to auto convert numeric values to actual numbers use `tableAutoConverted` method
+
+:include-java-doc: org/testingisdocumenting/webtau/data/DataCsv.java {entry: "listOfMapsAutoConverted"}
+
+:include-file: doc-artifacts/snippets/readingData/listOfMapsAutoConverted.groovy {title: "read list of maps from csv with auto conversion"}
+
+
+# JSON
+
+## List 
+
+:include-java-doc: org/testingisdocumenting/webtau/data/DataJson.java {entry: "list"}
+
+:include-json: data/flat-list.json {paths: ["root[0].name", "root[1].payload.info"], title: "data/flat-list.json"}
+
+:include-file: doc-artifacts/snippets/readingData/jsonList.groovy {title: "read json as list"}
+
+## Map
+
+:include-java-doc: org/testingisdocumenting/webtau/data/DataJson.java {entry: "map"}
+
+:include-json: data/root-map.json {paths: ["root.payload.info"], title: "data/root-map.json"}
+
+:include-file: doc-artifacts/snippets/readingData/jsonMap.groovy {title: "read json as map"}

webtau-docs/znai/utilities/introduction.md

@@ -0,0 +1,4 @@
+Webtau has several modules to help you simplify automation processes. All operations in the modules provide 
+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 

webtau-feature-testing/examples/data/flat-list.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "id1",
+    "name": "hello",
+    "payload": {
+      "info": "additional id1 payload"
+    }
+  },
+  {
+    "id": "id2",
+    "name": "world",
+    "payload": {
+      "info": "additional id2 payload"
+    }
+  }
+]

webtau-feature-testing/examples/data/root-map.json

@@ -0,0 +1,7 @@
+{
+  "id": "id1",
+  "name": "hello",
+  "payload": {
+    "info": "additional id1 payload"
+  }
+}