Skip to content

Commit 4918dac

Browse files
MykolaGolubyevMykolaGolubyev
authored
doc: redo intro page (#1445)
1 parent c0530bc commit 4918dac

File tree

6 files changed

+123
-131
lines changed

6 files changed

+123
-131
lines changed

‎webtau-docs/znai/GraphQL/introduction.md‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
WebTau `graphql.` module lets you exercise and validate a GraphQL API.
1+
WebTau `graphql` module lets you exercise and validate a GraphQL API.
22
It provides a simplified way to access the JSON response of an end-point and provides a DSL to execute queries and mutations.
33

44
``````tabs
@@ -38,14 +38,5 @@ Java:
3838
}
3939
```
4040
````
41-
4241
``````
4342

44-
45-
Before diving further into writing tests for your GraphQL server, please read through the HTTP testing documentation
46-
starting with the [Data node page](HTTP/data-node) as much of the same core principles apply to GraphQL also.
47-
48-
The main GraphQL specific features are covered in the subsequent pages:
49-
* [Queries and Mutations](GraphQL/queries-and-mutations)
50-
* [Customized GraphQL URLs](GraphQL/customized-graphql-urls)
51-
* [Report](GraphQL/report)

‎webtau-docs/znai/GraphQL/queries-and-mutations.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
1+
Before diving further into writing tests for your GraphQL server, please read through the HTTP testing documentation
2+
starting with the [Data node page](HTTP/data-node) as much of the same core principles apply to GraphQL also.
3+
4+
The main GraphQL specific features are covered in the subsequent pages:
5+
* [Queries and Mutations](GraphQL/queries-and-mutations)
6+
* [Customized GraphQL URLs](GraphQL/customized-graphql-urls)
7+
* [Report](GraphQL/report)
8+
19
# Executing Queries and Mutations
210

311
WebTau follows GraphQL's [Serving over HTTP best practices](https://graphql.org/learn/serving-over-http/) when invoking

‎webtau-docs/znai/HTTP/introduction.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
WebTau `http.` module lets you exercise and validate HTTP endpoints.
1+
WebTau `http` module lets you exercise and validate HTTP endpoints.
22
It provides a simplified way to make HTTP calls and validate responses
33

4+
Now with [Data Coverage](HTTP/data-coverage).
5+
46
```tabs
57
Groovy:
68
:include-file: org/testingisdocumenting/webtau/http/HttpResourceGroovyTest.groovy {
@@ -17,6 +19,8 @@ Java:
1719
}
1820
```
1921

22+
:include-cli-output: doc-artifacts/live-price-output.txt {title: "console output"}
23+
2024
``````tabs
2125
Groovy:
2226
````columns
@@ -46,3 +50,9 @@ Java:
4650
```
4751
````
4852
``````
53+
54+
:include-cli-output: doc-artifacts/com.example.tests.junit5.WeatherGroovyTest-console-output.txt {
55+
title: "console output",
56+
startLine: "executing",
57+
endLine: "executed"
58+
}

‎webtau-docs/znai/browser/introduction.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
WebTau `browser` module lets you interact with a browser.
1+
WebTau `browser` module lets you interact with a browser.
22

3-
It provides higher level abstractions to locate elements, encapsulate page implementation details and deal with
4-
async nature of modern UIs.
3+
High level abstractions streamline location, assertion and async logic.
54

6-
WebTau implements browser high level interactions by using [Selenium WebDriver](https://www.selenium.dev) to interact with the browser.
5+
WebTau leverages [Selenium WebDriver](https://www.selenium.dev) to do the heavy lifting.
76

87
```tabs
98
Groovy:
@@ -26,3 +25,7 @@ Java:
2625
}
2726
```
2827

28+
:include-cli-output: doc-artifacts/com.example.tests.junit5.WebSearchJavaTest-console-output.txt {
29+
title: "console output",
30+
surroundedBy: "searchByQuery"
31+
}

‎webtau-docs/znai/getting-started/what-is-this.md‎

Lines changed: 95 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,42 @@ WebTau (**Web** **T**est **au**tomation) - concise and expressive way to write e
44

55
:include-image: webtau-logo.png {scale: 0.5, align: "left"}
66

7-
Test your application across multiple layers:
8-
* REST API (Including [Data Coverage](HTTP/data-coverage))
9-
* GraphQL API
10-
* Browser
11-
* CLI
12-
* Database
13-
* Business Logic (JVM only)
7+
Test your application across multiple layers with the help of cross-cutting concepts:
8+
* [REST API](#rest-api)
9+
* [WebSocket](#websocket)
10+
* [GraphQL API](#graphql-api)
11+
* [Authorization Personas](#persona)
12+
* [Browser](#browser)
13+
* [Database](#database)
14+
* [CLI](#cli)
15+
* [Business Logic (JVM only)](#business-logic-jvm)
16+
* [REPL](#repl)
17+
* [Reporting](#reporting)
18+
* [Documentation Assistance](#documentation-assistance)
1419

15-
Use one layer to re-enforce tests on another. E.g. REST API layer to set up data for Browser test, or database layer
16-
to validate GraphQL API.
20+
There are many modules, but you can use any module you need independently, or use all the modules at once with convenient single imports.
21+
22+
Note: Tests can be written in any JVM language. Language specific syntactic sugar is available for `Groovy`.
23+
24+
# Rest API
25+
26+
:include-markdown: HTTP/introduction.md
27+
28+
[Read More](HTTP/CRUD-example)
29+
30+
# WebSocket
31+
32+
:include-markdown: web-socket/introduction.md
33+
34+
[Read More](web-socket/received-messages)
35+
36+
# GraphQL API
37+
38+
:include-markdown: GraphQL/introduction.md
39+
40+
[Read More](GraphQL/queries-and-mutations)
41+
42+
# Persona
1743

1844
Use [Persona](persona/introduction) concept to test API Authorization and collaboration Web Apps like chats and editors.
1945

@@ -37,141 +63,94 @@ Java:
3763
:include-json: doc-artifacts/bob-statement/response.json {title: "Bob server response"}
3864
```
3965

40-
Use powerful [REPL](REPL/experiments) mode to significantly speed up end-to-end tests development.
66+
# Browser
4167

42-
:include-cli-output: cli-tests/browser-repl-select/out.txt {title: "trying css selectors"}
68+
:include-markdown: browser/introduction.md
4369

44-
Capture test artifacts like API Responses, screenshots, command line output to automate your user facing documentation.
70+
[Read More](browser/basic-configuration)
4571

46-
Leverage out of the box [rich reporting](report/introduction)
72+
# Database
4773

48-
:include-image: doc-artifacts/reports/report-crud-separated-http-calls.png {fit: true}
74+
WebTau `db` module streamlines databases data setup, assertion and waiting on.
4975

50-
Tests can be written in any JVM language. Language specific syntactic sugar is available for `Groovy`.
76+
[Read More](database/introduction)
5177

52-
* [REST API example](#rest-api-example)
53-
* [GraphQL API example](#graphql-api-example)
54-
* [Browser example](#browser-example)
55-
* [DB example](#db-example)
56-
* [CLI example](#cli-example)
78+
:include-groovy: org/testingisdocumenting/webtau/db/DatabaseTest.groovy {
79+
entry: "use table data permute, above and guid to generate rows",
80+
title: "DB data setup example",
81+
bodyOnly: true,
82+
startLine: "def PRICES",
83+
endLine: "cell.above + 20",
84+
commentsType: "inline"
85+
}
5786

58-
# Rest API Example
87+
# CLI
5988

60-
WebTau provides a succinct DSL for exercising HTTP end points (e.g. REST APIs) and provides simplified way to
61-
assert responses.
89+
WebTau `cli` module helps with running and testing command line tools
6290

63-
``````tabs
91+
[Read More](cli/introduction)
6492

65-
Groovy:
66-
````columns
93+
:include-file: doc-artifacts/snippets/foreground-cli/withOutputValidation.groovy {
94+
title: "output validation"
95+
}
6796

68-
left:
69-
:include-file: scenarios/rest/simpleGet.groovy {title: "REST API test (Groovy runner)"}
70-
:include-file: com/example/tests/junit5/WeatherGroovyTest.groovy {title: "REST API test (JUnit5)"}
97+
# Business Logic (JVM)
7198

72-
right:
73-
```json {title: "Server Response"}
74-
{
75-
"temperature": 88
76-
}
77-
```
78-
````
79-
Java:
80-
````columns
99+
Powerful WebTau matchers help with complex data validation and provide rich output to help with failure investigation:
81100

82-
left:
83-
:include-file: com/example/tests/junit5/WeatherJavaTest.java {title: "REST API test (JUnit5 Java)"}
101+
[Read More](matchers/introduction)
84102

85-
right:
86-
```json {title: "Server Response"}
87-
{
88-
"temperature": 88
89-
}
90-
```
91-
````
103+
```tabs
104+
Groovy:
105+
:include-file: org/testingisdocumenting/webtau/MatchersGroovyTest.groovy {
106+
surroundedBy: "beans-table-example",
107+
commentsType: "inline"
108+
}
92109
93-
``````
110+
Java:
111+
:include-file: org/testingisdocumenting/webtau/MatchersTest.java {
112+
surroundedBy: "beans-table-example",
113+
commentsType: "inline"
114+
}
115+
```
94116

95-
# GraphQL API Example
117+
:include-cli-output: doc-artifacts/beans-table-compare-output.txt {title: "beans mismatches highlighted"}
96118

97-
Similar to HTTP APIs, WebTau also provides the ability to test GraphQL servers with its GraphQL DSL.
119+
# REPL
98120

99-
``````tabs
121+
Use powerful [REPL](REPL/experiments) mode to significantly speed up end-to-end tests development.
122+
Build your tests one step at a time without losing time on restarts.
100123

101-
Groovy:
102-
````columns
103-
104-
left:
105-
:include-file: scenarios/graphql/weatherQuery.groovy {title: "GraphQL API test (Groovy runner)"}
106-
:include-file: com/example/tests/junit4/GraphQLWeatherGroovyIT.groovy {title: "GraphQL API test (JUnit4)"}
107-
108-
right:
109-
```json {title: "Server Response"}
110-
{
111-
"data": {
112-
"weather": {
113-
"temperature": 88
114-
}
115-
}
116-
}
117-
```
118-
````
119-
Java:
120-
````columns
121-
122-
left:
123-
:include-file: com/example/tests/junit4/GraphQLWeatherJavaIT.java {title: "GraphQL API test (JUnit4 Java)"}
124-
125-
right:
126-
```json {title: "Server Response"}
127-
{
128-
"data": {
129-
"weather": {
130-
"temperature": 88
131-
}
132-
}
133-
}
134-
```
135-
````
124+
:include-cli-output: cli-tests/browser-repl-select/out.txt {title: "trying css selectors"}
136125

137-
``````
126+
# Reporting
138127

139-
# Browser Example
128+
Leverage out of the box [rich reporting](report/introduction).
129+
Report captures everything you do. Single self-sufficient file that can be slacked or emailed.
130+
Permalinks let you share the exact failure problem with your colleagues.
140131

141-
```tabs
142-
Groovy:
132+
:include-image: doc-artifacts/reports/report-crud-separated-http-calls.png {fit: true, border: true}
143133

144-
:include-file: scenarios/ui/searchWithPagesWaitTo.groovy {title: "Browser test (Groovy runner)"}
145-
:include-groovy: pages/SearchPage.groovy {title: "SearchPage.groovy"}
134+
# Documentation Assistance
146135

147-
:include-file: pages/Pages.groovy {
148-
title: "Pages.groovy",
149-
excludeRegexp: ["calculation", "form", "payments"]
150-
}
136+
WebTau helps you to capture test artifacts like [API Responses](HTTP/documentation-artifacts), [screenshots](browser/documentation-artifacts),
137+
command line output to automate your user facing documentation creation.
151138

152-
Java:
139+
:include-flow-chart: HTTP/documentation-flow.json
153140

154-
:include-file: com/example/tests/junit5/WebSearchJavaTest.java {title: "Browser test (JUnit 5)"}
155-
:include-file: com/example/tests/junit5/pages/SearchPage.java {title: "SearchPage.java"}
141+
Below is the example of API documentation with example of requests/response captured by a test:
156142

157-
:include-file: com/example/tests/junit5/pages/Pages.java {
158-
title: "Pages.java"
159-
}
160-
```
143+
:include-open-api: scenarios/rest/openapi/api-spec.json {operationId: "createEmployee" }
161144

162-
# DB Example
145+
```columns
146+
left:
147+
:include-json: doc-artifacts/employee-post/request.json { title: "request payload" }
163148
164-
:include-groovy: org/testingisdocumenting/webtau/db/DatabaseTest.groovy {
165-
entry: "use table data permute, above and guid to generate rows",
166-
title: "DB data setup example",
167-
bodyOnly: true,
168-
startLine: "def PRICES",
169-
endLine: "cell.above + 20",
170-
commentsType: "inline"
149+
right:
150+
:include-json: doc-artifacts/employee-post/response.json {
151+
title: "response payload",
152+
pathsFile: "doc-artifacts/employee-post/paths.json"
171153
}
154+
```
172155

173-
# CLI Example
174-
175-
:include-file: doc-artifacts/snippets/foreground-cli/withOutputValidation.groovy {
176-
title: "output validation"
177-
}
156+
:include-image: doc-artifacts/search.png {fit: true, annotate: true, title: "auto created screenshot and annotations"}

‎webtau-docs/znai/release-notes/1.52/doc-2023-04-17-intro-redo.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
* Doc: redo [WebTau intro](getting-started/what-is-this) and include HTTP Resource and Web Socket section

0 commit comments

Comments
 (0)