add znai exported source

Author: MykolaGolubyev

znaisrc/REST/CRUD-separated.md

@@ -0,0 +1,17 @@
+# Lazy Resource
+
+One of the benefits of separating one CRUD `scenario` into multiple is to be able to run one test at a time. 
+In order to do it we will use `createLazyResource`.
+
+:include-file: scenarios/rest/springboot/customerCrudSeparated.groovy {commentsType: "inline", title: "CRUD separated"}
+
+:include-file: scenarios/rest/springboot/Customer.groovy {commentsType: "inline", title: "Customer lazy resource"}
+
+Note: to run one scenario at a time use `sscenario` (additional `s` in front). [Read more](groovy-specific-runner/selective-run)
+
+# Report
+
+As you can see in the report below, each `CRUD` operation has its own entry. If you follow this pattern, then you
+can filter tests by `create`, `update`, `read`, `delete` to streamline investigation.
+
+:include-image: doc-artifacts/reports/report-crud-separated-http-calls.png {fit: true}

znaisrc/REST/CRUD.md

@@ -0,0 +1,48 @@
+# Example
+
+We have an app that exposes create, read, update, and delete operations for customer records. Records are being served 
+under `/customers`.
+
+Here is an example of a `CRUD` operations test.
+
+:include-file: scenarios/rest/springboot/customerCrud.groovy {commentsType: "inline"}
+
+# Implicit statusCode Check 
+
+If you don't have an explicit `statusCode` validation it will be automatically validated based on the rules below 
+
+| Method             | Expected Code |
+| ------------------ |---------------|
+| GET                | 200           |
+| POST               | 201           |
+| PUT                | 200           |
+| PUT (no content)   | 204           |
+| DELETE             | 200           |
+| DELETE (no content)| 204           |
+
+# Report
+
+After your test executions a report will be produced.
+
+:include-image: doc-artifacts/reports/report-crud-http-calls.png {fit: true}
+
+Note: asserted values are being tracked and highlighted inside the report 
+
+# Spring Boot
+
+WebTau is framework agnostic. However, to make a concrete example, the `/customer` `CRUD` endpoint
+is created by using [Spring Boot](https://projects.spring.io/spring-boot/).
+
+Three files are required to have a working REST endpoint with `CRUD` operations.
+
+1. Domain object
+
+    :include-file: com/example/demo/springboot/app/data/Customer.java {title: "Customer.java"}
+
+2. Repository
+
+    :include-file: com/example/demo/springboot/app/data/CustomerRepository.java {title: "CustomerRepository.java"}
+
+3. Entry point
+
+    :include-file: com/example/demo/springboot/app/SpringBootDemoApp.java {title: "SpringBootDemoApp.java"}

znaisrc/REST/JSON-schema.md

@@ -0,0 +1,37 @@
+# Validation
+
+Webtau supports validation of objects against [JSON Schema](https://json-schema.org/).  It is possible to validate either
+the entire body or just a specific field with the `complyWithSchema` matcher as shown in the two examples below:
+
+:include-groovy: doc-artifacts/snippets/json-schema/validateBody.groovy {title: "Validate entire body against JSON schema"}
+:include-groovy: doc-artifacts/snippets/json-schema/validateField.groovy {title: "Validate specific field against JSON schema"}
+
+Both examples above validate against the following schema:
+
+:include-json: examples/schemas/valid-schema.json {title: "Correct schema for the example above"}
+
+# Error messages
+
+Using the first example above, an invalid schema will generate an error similar to:
+```
+invalid schema (examples/scenarios/rest/jsonSchema/validateSchema.groovy)
+> executing HTTP GET http://localhost:8080/weather
+  X failed expecting body to comply with schema invalid-schema.json : 
+      body expected to comply with schema invalid-schema.json
+      [#: required key [anotherField] not found, #/temperature: expected type: Boolean, found: Integer]
+{
+  "temperature": 88
+}
+```
+
+The schema used in validation to generate this error is as follows:
+
+:include-json: examples/schemas/invalid-schema.json {title: "Incorrect schema for the example above"}
+
+# Configuration
+
+The path to the schema file specified in `complyWithSchema` can be relative or absolute.  If it's relative, it'll be
+relative to the `jsonSchemasDir` specified in configuration and if not specified then relative to working directory.
+For example:
+
+:include-file: scenarios/rest/jsonSchema/webtau.cfg {title: "Configuration"}

znaisrc/REST/PDF.md

@@ -0,0 +1,11 @@
+# Asserting Text
+
+If response contains a pdf file you can assert its content using `pdf(body)` function.
+
+:include-groovy: com/twosigma/webtau/pdf/PdfHttpTest.groovy {entry: "download pdf and assert page text using contains", bodyOnly: true}
+ 
+If more than one assertion needs to be made, assign `pdf` result to a local variable.
+ 
+:include-groovy: com/twosigma/webtau/pdf/PdfHttpTest.groovy {entry: "download pdf and assert page text using equal and contains", bodyOnly: true}
+
+Note: use pdf assertions for sanity checks like presence of correct client names or account numbers. Leave comprehensive pdf generation test to unit tests.

znaisrc/REST/complex-types.md

@@ -0,0 +1,23 @@
+# Contain
+
+Use `contain` matcher to test scenarios like search or list of recently created entries. 
+This way you don't have to assume an existing state of your backend under test.
+ 
+:include-json: doc-artifacts/list-match/response.json {title: "Response"}
+
+Given the response, we want to make sure there is an entry with a specified `firstName` and `lastName`.
+ 
+:include-file: examples/scenarios/rest/springboot/listContain.groovy
+
+# List Of Objects
+
+If you want to make sure that all the values in the list are what you need - use `TableData`.
+
+:include-file: examples/scenarios/rest/springboot/listMatch.groovy
+
+# Order Agnostic Match
+
+Use `*key` column(s) if list order is not guaranteed
+
+:include-file: examples/scenarios/rest/springboot/listMatchByKey.groovy
+ 

znaisrc/REST/data-node.md

@@ -0,0 +1,89 @@
+# Special Values
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "use groovy closure as validation", bodyOnly: true}
+
+Values that you access inside validation block are special values of `DataNode` type. When you assert them using `should` statement
+they act as proxies that record every assertion that you do. 
+
+
+# Extracting Values
+
+As you have seen in [CRUD example](REST/CRUD) you can return values back from a validation block.
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "can return simple value from get", bodyOnly: true}
+
+When you return a value from a validation block, it automatically gets converted to its correspondent primitive. 
+
+Note: asserting that value after returning will not track and associated assertions with the call anymore. Use it only
+to get values required for consequent test calls.  
+
+# Properties On Lists
+
+:include-json: objectTestResponse.json
+
+If you have a list of objects like `complexList` above, you can access all its children property value with `complexList.k2`.
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "groovy children key shortcut", bodyOnly: true}
+
+# Path based properties access
+
+Primarily for Java users, webtau supports the ability to query properties of a `DataNode` via a path instead of chaining
+`get(String name)` calls.  For example, to obtain a simple property:
+
+:include-java: com/twosigma/webtau/http/HttpJavaTest.java {entry: "canQueryNodeByPath", bodyOnly: true}
+
+It is also possible to query arrays, including the ability to query for the Nth element from the end:
+
+:include-java: com/twosigma/webtau/http/HttpJavaTest.java {entry: "canQuerySpecificListElementByPath", bodyOnly: true}
+
+Similarly to the Groovy example in [Properties On Lists](REST/data-node#properties-on-lists), it is possible to access 
+all children property values:
+
+:include-java: com/twosigma/webtau/http/HttpJavaTest.java {entry: "canQueryListByNodePath", bodyOnly: true}
+
+# If-Else Logic
+
+Even though values that you access inside validation block are special values of `DataNode` type, you can still
+perform simple `if-else` like logic checks on them. Accessing the values will mark them as "touched" for data coverage statistic. 
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "if-else logic", bodyOnly: true, title: "simple if-else logic"}
+
+Warning: Comparison of complex values is not properly implemented due to current Groovy API implementation details
+
+# Each
+
+Special values inside assertion block have convenient methods
+
+`each` to iterate over a list
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "groovy each on simple list", bodyOnly: true, title: "List of simple values"}
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "groovy each on complex list", bodyOnly: true, title: "List of complex values"}
+
+
+# Find
+
+`find` to find a single value
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "groovy find on list", bodyOnly: true}
+
+
+and `findAll` to find all the values matching predicate
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "groovy findAll on list", bodyOnly: true}
+
+Note: While values inside a predicate are normal values, the result of `find` and `findAll` is still `DataNode`
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "groovy find on list of objects", bodyOnly: true}
+
+# Collect
+
+Use `collect` to transform a collection of items
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "groovy transform list", bodyOnly: true}
+
+# Combine
+
+Methods `find` and `collect` can be chained
+ 
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "groovy findAll, collect, and sum", bodyOnly: true}

znaisrc/REST/documentation-flow.json

@@ -0,0 +1,26 @@
+{
+  "nodes": [
+    {
+      "id": "build",
+      "label": "Build"
+    },
+    {
+      "id": "deploy",
+      "label": "Deploy"
+    },
+    {
+      "id": "testrun",
+      "label": "Test Run",
+      "highlight": true
+    },
+    {
+      "id": "documentation",
+      "label": "Documentation"
+    }
+  ],
+  "edges": [
+    ["build", "deploy"],
+    ["deploy", "testrun"],
+    ["testrun", "documentation"]
+  ]
+}

znaisrc/REST/documentation.md

@@ -0,0 +1,70 @@
+# Scenarios
+
+You provide `REST endpoints` so users can execute various scenarios.
+You need to test those scenarios and then document them.
+
+To automate the process, let's capture executed scenarios and use them inside your documentation.
+
+# Capturing Test Artifacts
+
+To capture artifacts use `http.doc.capture`:
+
+:include-file: scenarios/rest/simplePost.groovy {title: "test.groovy", commentsType: "inline"}
+
+An `employee-get` directory will be created containing a number of test artifacts.
+
+# Test Artifacts Location
+
+By default, the directory will be created in the current working directory.
+To change it add `docPath` to your `webtau.cfg` file.
+
+:include-file: examples/scenarios/rest/docArtifacts.cfg {title: "webtau.cfg"}
+
+# Test Artifacts
+
+A number of artifacts will be created depending on the exact call being captured.
+
+## Request and response payloads
+
+Request bodies are captured in either `request.json`, `request.pdf` or `request.data` depending on the type. 
+
+:include-json: doc-artifacts/employee-post/request.json {title: "employee-post/request.json" }
+
+Similarly, response bodies are captured in either `response.json`, `response.pdf` or `response.data`.
+
+:include-json: doc-artifacts/employee-get/response.json {title: "employee-get/response.json" }
+
+## Request and response headers
+
+Just like payloads, request and response headers are captured in `request.header.txt` and `response.header.txt`
+respectively. These files contain a header per line with the name and values colon separated.  The values
+are redacted for any potentially sensitive headers.
+
+:include-json: doc-artifacts/echo-body-and-header-redacted/request.header.txt {title: "redacted request.header.txt"}
+
+## Response body assertions
+
+Any assertions you perform on the response body in your scenarios are captured in a `paths.json` file.  This
+contains an array with the list of paths within the body whose values were asserted.
+
+:include-json: doc-artifacts/employee-get/paths.json {title: "employee-get/paths.json" }
+
+
+## Request URLs
+
+The actual request URL is captured in two forms into two different files:
+* `request.fullurl.txt` - contains the full URL
+* `request.url.txt` - contains only the part specified in the http call in the scenario
+
+:include-file: doc-artifacts/url-capture/request.url.txt {title: "request.url.txt"}
+
+:include-file: doc-artifacts/url-capture/request.fullurl.txt {title: "request.fullurl.txt"}
+
+# Document REST calls
+
+If you have user facing scenario tests, capture them and refer to them inside your documentation.
+Set your documentation build pipeline like below.
+
+:include-flow-chart: documentation-flow.json     
+
+Combine REST requests and responses with Open API generated specs for complete documentation. 

znaisrc/REST/files-upload.md

@@ -0,0 +1,29 @@
+# File System Content
+
+In following examples backend expects a file passed as `multipart/form-data`. File content is expected to be stored in `file` field.  
+Backend responds with received file name and file description.  
+
+To `POST` form data, you need to use the same `http.post` statement as you saw in previous examples. 
+Second parameter should be `http.formData` instead of a map payload we used for `JSON`. 
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "file upload example simple", bodyOnly: true}
+
+Use `http.formFile` to override file name that is being sent to the backend.
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "file upload example with file name override", bodyOnly: true}
+
+Multiple form fields can be specified like in the example below. 
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "file upload example multiple fields", bodyOnly: true}
+
+# In-Memory Content
+
+If your test already has content, you can explicitly pass it as is.
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "file upload example with in-memory content", bodyOnly: true}
+
+Note: no file name is passed and this particular backend generated file name on your behalf.
+
+Use `http.formFile` to provide a file name
+
+:include-groovy: com/twosigma/webtau/http/HttpGroovyTest.groovy {entry: "file upload example with in-memory content and file name", bodyOnly: true}