Scenarios

You document REST endpoints so users can use them to achieve various goals. You also need to make sure that documented scenarios work as advertised.To automate the process, capture executed scenarios and use them inside your documentation.

Capturing Test Artifacts

To capture REST artifacts use http.doc.capture : package scenarios.rest import static org.testingisdocumenting.webtau.WebTauDsl.http import static org.testingisdocumenting.webtau.WebTauGroovyDsl.scenario scenario("extracting id after POST to use inside GET request") { def id = http.post("/employee", [firstName: 'FN', lastName: 'LN']) { return id } http.doc.capture('employee-post') http.get("/employee/$id") { firstName.should == 'FN' lastName.should == 'LN' } http.doc.capture('employee-get') // capture previous HTTP call into <docDir>/employee-get } 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.groovy file. url = "http://localhost:8180" docPath = "doc-artifacts"

Test Artifacts

A number of artifacts will be created depending on the exact call being captured.Request bodies are captured in either request.json , request.pdf or request.data depending on the type.Similarly, response bodies are captured in either response.json , response.pdf or response.data .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.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.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 /params?a=1&b=text http://10.1.0.4:46329/params?a=1&b=text

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.Combine REST requests and responses with Open API generated specs for complete documentation.