webship-js 2.0.10 → 2.0.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.circleci/config.yml +10 -1
- package/.drone.yml +7 -7
- package/.github/ISSUE_TEMPLATE/issue.md +37 -0
- package/.github/PULL_REQUEST_TEMPLATE.md +24 -0
- package/.github/workflows/github-actions.yml +101 -4
- package/.gitlab-ci.yml +9 -4
- package/.harness/webship-js-pipeline.yml +5 -6
- package/.semaphore/semaphore.yml +6 -9
- package/.teamcity/settings.kts +7 -6
- package/.travis.yml +6 -1
- package/AGENTS.md +1 -1
- package/CLAUDE.md +69 -24
- package/Jenkinsfile +5 -3
- package/README.md +13 -1
- package/azure-pipelines.yml +17 -8
- package/bamboo-specs/bamboo.yml +9 -15
- package/bin/generate-reports.js +51 -7
- package/bin/init-webship.js +127 -23
- package/bitbucket-pipelines.yml +5 -1
- package/buildspec.yml +6 -7
- package/cloudbuild.yaml +28 -12
- package/codefresh.yml +6 -6
- package/cucumber.js +46 -11
- package/docs/00-quick-start.md +38 -7
- package/docs/02-bbr-smart-waits.md +21 -10
- package/docs/03-selector-registry.md +24 -0
- package/docs/04-step-reference.md +53 -27
- package/docs/05-web-first-assertions.md +6 -0
- package/docs/07-auth-state.md +1 -1
- package/docs/08-clock-mocking.md +21 -2
- package/docs/09-api-testing.md +40 -2
- package/docs/10-accessibility.md +2 -0
- package/docs/11-debugging.md +24 -1
- package/docs/12-ai-agent-guide.md +8 -1
- package/docs/13-faq.md +75 -1
- package/docs/14-recipes-cookbook.md +2 -0
- package/docs/15-tag-conventions.md +5 -1
- package/docs/16-ci-cd.md +161 -124
- package/docs/README.md +5 -5
- package/docs/advanced-screenshots.md +3 -1
- package/docs/api-step-definitions.md +16 -2
- package/docs/global-settings.md +70 -18
- package/docs/install-webship-js/ddev-webship-js.md +3 -0
- package/docs/install-webship-js.md +16 -2
- package/docs/step-definitions/then-i-should-see.md +14 -1
- package/docs/step-definitions/then-item-checkbox.md +2 -0
- package/docs/step-definitions/when-i-fill.md +4 -0
- package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
- package/examples/a11y-legacy-widget.html +34 -0
- package/examples/auth-state.html +42 -0
- package/examples/choice-controls.html +29 -0
- package/examples/clock.html +33 -0
- package/examples/datetime-fields.html +52 -0
- package/examples/downloads/webship-archive.zip +0 -0
- package/examples/downloads/webship-notes.txt +4 -0
- package/examples/downloads/webship-report.csv +4 -0
- package/examples/downloads.html +16 -0
- package/examples/element-selector-hint.html +16 -0
- package/examples/element-viewport.html +42 -0
- package/examples/field-states.html +27 -0
- package/examples/field-types.html +98 -0
- package/examples/fill-in-empty.html +26 -0
- package/examples/fill-unreachable.html +27 -0
- package/examples/iframe-inner.html +20 -0
- package/examples/iframe-nested.html +16 -0
- package/examples/iframe-newsletter.html +29 -0
- package/examples/iframe-order.html +26 -0
- package/examples/iframe-outer.html +15 -0
- package/examples/iframe.html +21 -0
- package/examples/javascript-errors.html +35 -0
- package/examples/links.html +1 -0
- package/examples/metatags.html +18 -0
- package/examples/mouse-and-pointer.html +83 -0
- package/examples/multi-value-fields.html +54 -0
- package/examples/native-dialogs.html +8 -0
- package/examples/network.html +83 -0
- package/examples/registered-names.html +15 -0
- package/examples/scroll-horizontal.html +50 -0
- package/examples/select-by-label.html +33 -0
- package/examples/selectors-position.html +29 -0
- package/examples/settle-budget.html +21 -0
- package/examples/sorted-tables.html +38 -0
- package/examples/storage.html +57 -0
- package/examples/text-matching.html +48 -0
- package/examples/text-order.html +25 -0
- package/examples/touch.html +22 -0
- package/examples/viewport-size.html +24 -0
- package/examples/viewport-top.html +36 -0
- package/examples/wait-conditions.html +69 -0
- package/examples/web-first.html +99 -0
- package/package.json +24 -2
- package/playwright.config.ts +3 -1
- package/tests/assets/catalog.xml +19 -0
- package/tests/assets/feed-namespaced.xml +13 -0
- package/tests/assets/sitemap.xml +14 -0
- package/tests/assets/webship-site-expected.yaml +21 -0
- package/tests/assets/webship-site.schema.json +46 -0
- package/tests/assets/webship-site.yaml +21 -0
- package/tests/check-api-launch-url.js +106 -0
- package/tests/check-assets.js +103 -0
- package/tests/check-attachments.js +105 -0
- package/tests/check-breakpoints.js +117 -0
- package/tests/check-clock.js +143 -0
- package/tests/check-config.js +90 -0
- package/tests/check-context.js +215 -0
- package/tests/check-dry-run.js +104 -0
- package/tests/check-examples.js +241 -0
- package/tests/check-exit-report.js +141 -0
- package/tests/check-javascript-errors.js +105 -0
- package/tests/check-must-fail.js +85 -0
- package/tests/check-paths.js +82 -0
- package/tests/check-report.js +119 -0
- package/tests/check-scaffold.js +246 -0
- package/tests/check-screenshots.js +117 -0
- package/tests/check-settle-verbs.js +137 -0
- package/tests/check-time-limit.js +104 -0
- package/tests/check-video.js +156 -0
- package/tests/check-world.js +167 -0
- package/tests/features/a11y.feature +18 -0
- package/tests/features/api-base-url.feature +25 -0
- package/tests/features/api-form-data.feature +18 -0
- package/tests/features/api-json-paths.feature +24 -0
- package/tests/features/api-response-contains.feature +21 -0
- package/tests/features/api-response-header-presence.feature +17 -0
- package/tests/features/api-response-header.feature +17 -0
- package/tests/features/api-saved-placeholders.feature +37 -0
- package/tests/features/api-step-definitions-individual.feature +1 -1
- package/tests/features/api-tables.feature +40 -0
- package/tests/features/auth-state.feature +32 -0
- package/tests/features/breakpoints.feature +25 -0
- package/tests/features/choice-controls.feature +35 -0
- package/tests/features/clock.feature +27 -0
- package/tests/features/complete-api-testing-examples.feature +1 -1
- package/tests/features/cookie.feature +9 -0
- package/tests/features/datetime-field-lookup.feature +29 -0
- package/tests/features/dialog.feature +27 -0
- package/tests/features/element-selector-hint.feature +14 -0
- package/tests/features/element.feature +47 -0
- package/tests/features/field-state.feature +21 -0
- package/tests/features/field.feature +104 -0
- package/tests/features/file-download.feature +64 -0
- package/tests/features/fill-in-empty-value.feature +41 -0
- package/tests/features/fill-reachable.feature +13 -0
- package/tests/features/iframe-nested.feature +43 -0
- package/tests/features/iframe.feature +83 -0
- package/tests/features/javascript-tolerated-errors.feature +20 -0
- package/tests/features/javascript.feature +47 -0
- package/tests/features/link.feature +11 -0
- package/tests/features/metatag.feature +38 -0
- package/tests/features/modal-open.feature +13 -0
- package/tests/features/mouse-and-pointer.feature +86 -0
- package/tests/features/multi-value-field-lookup.feature +30 -0
- package/tests/features/network-mocking.feature +80 -0
- package/tests/features/registered-names.feature +14 -0
- package/tests/features/responsive.feature +27 -0
- package/tests/features/scroll-horizontal.feature +55 -0
- package/tests/features/select-by-label.feature +31 -0
- package/tests/features/selector-files.feature +14 -0
- package/tests/features/selectors-position.feature +41 -0
- package/tests/features/selectors-table-header.feature +35 -0
- package/tests/features/settle-budget.feature +11 -0
- package/tests/features/sorted-tables.feature +19 -0
- package/tests/features/storage-quoted-values.feature +26 -0
- package/tests/features/storage.feature +98 -0
- package/tests/features/test--then--i-see-locator.feature +13 -0
- package/tests/features/test--then--i-should--see-text-in-element.feature +9 -1
- package/tests/features/test--then--the-field-should-contain-value.feature +8 -0
- package/tests/features/text-matching.feature +38 -0
- package/tests/features/text-order.feature +14 -0
- package/tests/features/touch.feature +21 -0
- package/tests/features/video.feature +1 -0
- package/tests/features/viewport-top.feature +13 -0
- package/tests/features/wait.feature +89 -0
- package/tests/features/web-first.feature +100 -0
- package/tests/features/xml-namespaces.feature +34 -0
- package/tests/features/xml.feature +96 -0
- package/tests/features/yaml.feature +75 -0
- package/tests/must-fail/api-json-paths.feature +21 -0
- package/tests/must-fail/api-response-contains.feature +23 -0
- package/tests/must-fail/api-response-header-presence.feature +17 -0
- package/tests/must-fail/api-response-header.feature +21 -0
- package/tests/must-fail/api-without-base-url.feature +11 -0
- package/tests/must-fail/assertions.feature +96 -0
- package/tests/must-fail/breakpoints.feature +15 -0
- package/tests/must-fail/choice-controls.feature +25 -0
- package/tests/must-fail/clock.feature +11 -0
- package/tests/must-fail/datetime-field.feature +10 -0
- package/tests/must-fail/element-selector-hint.feature +17 -0
- package/tests/must-fail/field-state.feature +20 -0
- package/tests/must-fail/fill-field.feature +30 -0
- package/tests/must-fail/iframe-text.feature +17 -0
- package/tests/must-fail/modal-open.feature +26 -0
- package/tests/must-fail/multi-value-field.feature +18 -0
- package/tests/must-fail/registered-names.feature +25 -0
- package/tests/must-fail/select-list.feature +15 -0
- package/tests/must-fail/selector-files.feature +10 -0
- package/tests/must-fail/sorted-tables.feature +20 -0
- package/tests/must-fail/storage-before-a-page.feature +13 -0
- package/tests/must-fail/text-matching.feature +16 -0
- package/tests/must-fail/text-order.feature +15 -0
- package/tests/must-fail/viewport-top.feature +20 -0
- package/tests/must-fail/waits.feature +51 -0
- package/tests/must-fail/yaml-numbers.feature +48 -0
- package/tests/reports/README.md +2 -2
- package/tests/step-definitions/a11y.steps.js +36 -23
- package/tests/step-definitions/action.steps.js +22 -8
- package/tests/step-definitions/api.steps.js +349 -67
- package/tests/step-definitions/assertion.steps.js +327 -63
- package/tests/step-definitions/auth.steps.js +15 -18
- package/tests/step-definitions/clock.steps.js +22 -0
- package/tests/step-definitions/debug.steps.js +8 -0
- package/tests/step-definitions/dialog.steps.js +9 -2
- package/tests/step-definitions/element.steps.js +135 -18
- package/tests/step-definitions/field.steps.js +523 -80
- package/tests/step-definitions/file-download.steps.js +74 -10
- package/tests/step-definitions/form.steps.js +76 -29
- package/tests/step-definitions/iframe.steps.js +89 -29
- package/tests/step-definitions/input.steps.js +26 -7
- package/tests/step-definitions/javascript.steps.js +64 -22
- package/tests/step-definitions/modal.steps.js +79 -13
- package/tests/step-definitions/navigation.steps.js +14 -0
- package/tests/step-definitions/network.steps.js +15 -5
- package/tests/step-definitions/response.steps.js +6 -4
- package/tests/step-definitions/responsive.steps.js +26 -33
- package/tests/step-definitions/screenshot.steps.js +26 -9
- package/tests/step-definitions/scroll.steps.js +20 -0
- package/tests/step-definitions/selectors.steps.js +104 -51
- package/tests/step-definitions/storage.steps.js +41 -16
- package/tests/step-definitions/table.steps.js +81 -6
- package/tests/step-definitions/video.steps.js +52 -55
- package/tests/step-definitions/wait.steps.js +209 -54
- package/tests/step-definitions/web-first.steps.js +69 -35
- package/tests/step-definitions/webship.js +807 -128
- package/tests/step-definitions/xml.steps.js +124 -28
- package/tests/step-definitions/yaml.steps.js +90 -46
- package/.scratch/commit.txt +0 -14
- package/.scratch/docs.py +0 -42
- package/.scratch/echo-server.js +0 -8
- package/.scratch/echo.js +0 -35
- package/.scratch/echo.pid +0 -1
- package/.scratch/features/cookies.feature +0 -22
- package/.scratch/http.pid +0 -1
- package/.scratch/https.pid +0 -1
- package/.scratch/issue.md +0 -49
- package/.scratch/one.js +0 -2
- package/.scratch/one.json +0 -280
- package/.scratch/patch.py +0 -163
- package/.scratch/pr.md +0 -30
package/docs/09-api-testing.md
CHANGED
|
@@ -19,6 +19,8 @@ Given the API base URL is "https://api.example.com"
|
|
|
19
19
|
| Accept | application/json |
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
+
The base URL, like the headers, the body and the placeholders, belongs to the scenario that sets it: it is reset before every scenario, so set it in each scenario or in a `Background`. A path (`"/"`, `"/api/v2"`) is joined to the launch URL of the run (`worldParameters.launchUrl`, which `LAUNCH_URL` sets), the way `I am on "…"` joins one. A request step given a whole URL (`When I send a GET request to "https://api.example.com/users"`) sends it as written; a request to a path in a scenario that set no base URL fails at once and says so.
|
|
23
|
+
|
|
22
24
|
## Sending requests
|
|
23
25
|
|
|
24
26
|
```gherkin
|
|
@@ -29,10 +31,14 @@ When I send a POST request to "/users" with body:
|
|
|
29
31
|
"""
|
|
30
32
|
When I send a PUT request to "/users/1" with form data:
|
|
31
33
|
"""
|
|
32
|
-
name=Alice
|
|
34
|
+
name=Alice
|
|
35
|
+
role=admin
|
|
36
|
+
redirect=/account?tab=profile
|
|
33
37
|
"""
|
|
34
38
|
```
|
|
35
39
|
|
|
40
|
+
Form data takes one `name=value` field per line. Each line is split on its first `=`, so a value keeps the `=` it holds (`redirect=/account?tab=profile` sends `/account?tab=profile`).
|
|
41
|
+
|
|
36
42
|
## Asserting responses
|
|
37
43
|
|
|
38
44
|
```gherkin
|
|
@@ -40,12 +46,20 @@ Then the API response code should be 200
|
|
|
40
46
|
And the API response should contain "Alice"
|
|
41
47
|
And the API response should not contain "<script>"
|
|
42
48
|
And the response header "content-type" should contain "json"
|
|
49
|
+
And the API response should contain the header "ETag"
|
|
50
|
+
And the API response should not contain the header "X-Powered-By"
|
|
43
51
|
And the response should be valid JSON
|
|
44
52
|
And the JSON property "user.name" should be "Alice"
|
|
45
53
|
And the JSON response should have property "user.id"
|
|
46
54
|
And the JSON response should not have property "password"
|
|
47
55
|
```
|
|
48
56
|
|
|
57
|
+
The JSON property steps name a property by a dot path (`user.name`, `orders.0.status`, `orders[0].status`) or by a JSON Pointer (`/user/name`, `/orders/0/status`), the form the YAML steps take. When a part of the path is missing, the failure says which one and where the path stopped.
|
|
58
|
+
|
|
59
|
+
`the API response should contain "…"` and `the API response should not contain "…"` read the body of the response the same way: the text is looked for anywhere in it, letter case ignored, after the placeholders set with `I set placeholder` are replaced. A text one of them finds, the other refuses. A failure names the request the response answers.
|
|
60
|
+
|
|
61
|
+
`the response header "<name>" should be "<value>"` compares the whole value of the header (white space around it trimmed), and `should contain "<text>"` looks for a part of it; the header name is matched in any letter case. A server that sends `application/json; charset=utf-8` passes `should contain "application/json"`, not `should be "application/json"`.
|
|
62
|
+
|
|
49
63
|
## Combining UI and API
|
|
50
64
|
|
|
51
65
|
```gherkin
|
|
@@ -79,6 +93,8 @@ When I send a POST request to "/users" with values:
|
|
|
79
93
|
| email | alice@example.com |
|
|
80
94
|
```
|
|
81
95
|
|
|
96
|
+
The tables of `with values:`, `I set the request body with:` and `I set the following headers:` send every row, the first one included. A first row that names the columns (`| name | value |`, `| header | value |`, `| field | value |`) is a header row and is left out.
|
|
97
|
+
|
|
82
98
|
Assert against an exact JSON shape with a doc string:
|
|
83
99
|
|
|
84
100
|
```gherkin
|
|
@@ -88,11 +104,33 @@ Then the API response should contain json:
|
|
|
88
104
|
"""
|
|
89
105
|
```
|
|
90
106
|
|
|
91
|
-
Substitute placeholders
|
|
107
|
+
Substitute placeholders set in the scenario or saved from an earlier response:
|
|
92
108
|
|
|
93
109
|
```gherkin
|
|
94
110
|
Given I set placeholder "{{userId}}" to "42"
|
|
95
111
|
When I send a GET request to "/users/{{userId}}"
|
|
112
|
+
|
|
113
|
+
When I send a POST request to "/login" with body:
|
|
114
|
+
"""
|
|
115
|
+
{"username": "editor", "password": "{{password}}"}
|
|
116
|
+
"""
|
|
117
|
+
And I save the JSON property "token" as placeholder "{{token}}"
|
|
118
|
+
And I set the header "Authorization" to "Bearer {{token}}"
|
|
119
|
+
And I send a GET request to "/me"
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`I save the JSON property "<path>" as placeholder "<name>"` names the property the way the JSON property steps do. Placeholders are replaced as plain text in URLs, headers (when the request is sent, so a header set in a `Background` gets a value saved later), bodies and the checks.
|
|
123
|
+
|
|
124
|
+
A custom step reaches the same state through the exports of `api.steps.js`:
|
|
125
|
+
|
|
126
|
+
```js
|
|
127
|
+
const api = require('webship-js/tests/step-definitions/api.steps');
|
|
128
|
+
|
|
129
|
+
Then('the saved token is not empty', function () {
|
|
130
|
+
if (!api.getPlaceholder('{{token}}')) throw new Error('no token was saved');
|
|
131
|
+
});
|
|
132
|
+
// Also: api.getApiResponse(), api.setPlaceholder(name, value),
|
|
133
|
+
// api.replacePlaceHolder(text), api.getNestedProperty(object, path).
|
|
96
134
|
```
|
|
97
135
|
|
|
98
136
|
For HTTP basic auth on the next page navigation, see also `path.steps.js`:
|
package/docs/10-accessibility.md
CHANGED
|
@@ -133,6 +133,8 @@ One step runs axe at the level (AA by default) and every structural probe in thi
|
|
|
133
133
|
|
|
134
134
|
It reports every failure at once, not the first. A finding axe already named is not repeated by the probe that covers the same thing. The print form reports without failing, which is the way to see where a page stands before choosing a gate.
|
|
135
135
|
|
|
136
|
+
The two print steps (`I print the full accessibility check`, `I print accessibility violations`) write what they found to the console and attach the same text to their step, so the JSON report, the HTML report and a CI artifact show it under the step.
|
|
137
|
+
|
|
136
138
|
The skip link, focus, ARIA role and required-field steps are not part of it. Add them beside it when you need them.
|
|
137
139
|
|
|
138
140
|
## axe-core full audit
|
package/docs/11-debugging.md
CHANGED
|
@@ -4,7 +4,7 @@ When a scenario fails, you have several layers of evidence to inspect.
|
|
|
4
4
|
|
|
5
5
|
## Auto-screenshot on failure
|
|
6
6
|
|
|
7
|
-
Every failed step automatically writes a screenshot under `screenshots/` with a timestamped filename. Configure in `cucumber.js`:
|
|
7
|
+
Every failed step automatically writes a screenshot under `screenshots/` with a timestamped filename, and attaches it to the failed step in the JSON report: the HTML report shows it under that step. Configure in `cucumber.js`:
|
|
8
8
|
|
|
9
9
|
```js
|
|
10
10
|
worldParameters: {
|
|
@@ -55,6 +55,8 @@ Then there should be no JavaScript errors
|
|
|
55
55
|
|
|
56
56
|
After every run, `tests/reports/cucumber_report.html` is regenerated. Open it for a clickable summary of features, scenarios, durations, screenshots, and per-step output.
|
|
57
57
|
|
|
58
|
+
The report is built from the JSON report of the run: the file named by `WEBSHIP_REPORT_JSON`, else the file of the `json:` formatter of the command line (`--format json:reports/run.json`), else the one of `cucumber.js`, else `tests/reports/cucumber_report.json`. With `--parallel`, it is built once, by the process that runs cucumber-js, after the whole JSON report is written. When the run wrote no JSON report, one line says so.
|
|
59
|
+
|
|
58
60
|
Disable: `WEBSHIP_REPORT_DISABLE=1`.
|
|
59
61
|
|
|
60
62
|
### Export to PDF
|
|
@@ -118,6 +120,27 @@ contextOptions: {
|
|
|
118
120
|
}
|
|
119
121
|
```
|
|
120
122
|
|
|
123
|
+
## Reading a failure
|
|
124
|
+
|
|
125
|
+
The text, element, link, CSS and response assertions and the targeted waits fail with one shape: what was looked for and for how long, what was found where that helps, the address of the page, and a hint.
|
|
126
|
+
|
|
127
|
+
```
|
|
128
|
+
✖ Then I should see "Completely different words" in the "h1" element
|
|
129
|
+
The element "h1" does not contain "Completely different words".
|
|
130
|
+
Found: "About Us"
|
|
131
|
+
Page: http://localhost:8080/about-us.html
|
|
132
|
+
Hint: check the spelling and the letter case; for a field the step reads its value.
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
✖ When I wait for the text "Never arrives" to appear
|
|
137
|
+
The text "Never arrives" did not appear within 10 seconds.
|
|
138
|
+
Page: http://localhost:8080/about-us.html
|
|
139
|
+
Hint: check the spelling and the letter case; the step reads the visible text of the page.
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
`tests/must-fail/` holds scenarios that must fail, each with the message it must fail with (`Fails with: …` in its description). `npm run test:must-fail` runs them against the `examples/` pages and checks the message, the page and the hint; CI runs it before the suite. A step whose failure message changes gets its must-fail scenario updated in the same change.
|
|
143
|
+
|
|
121
144
|
## Common diagnoses
|
|
122
145
|
|
|
123
146
|
| Symptom | Likely cause | Fix |
|
|
@@ -209,7 +209,14 @@ When asked to add a custom step:
|
|
|
209
209
|
4. Add a JSDoc block with at least 5 `Example #N:` Gherkin lines that
|
|
210
210
|
match the step pattern.
|
|
211
211
|
5. Use plain English in the step text. No camelCase identifiers.
|
|
212
|
-
6. Run the audit:
|
|
212
|
+
6. Run the audit: `npm run test:examples`. It fails when a definition has
|
|
213
|
+
no JSDoc description or no example, when a step line of an example
|
|
214
|
+
matches no definition or more than one, and when a feature step does.
|
|
215
|
+
7. Do not start a custom step with an unquoted phrase that a bare-name
|
|
216
|
+
selector step also reads (`I click next button in tour`): the bare-name
|
|
217
|
+
click matches any unquoted words after "click". Quote the argument and
|
|
218
|
+
give the step words of its own (`I click "Next" in the tour`), then
|
|
219
|
+
check with `npx cucumber-js --dry-run`.
|
|
213
220
|
|
|
214
221
|
### Recipe AI-3: Maintain tests after a UI change
|
|
215
222
|
|
package/docs/13-faq.md
CHANGED
|
@@ -23,6 +23,56 @@ For most tests, no. Use the built-in steps. Write JavaScript only when
|
|
|
23
23
|
your business has a step that no preset covers — and even then, place
|
|
24
24
|
it in `tests/step-definitions/<topic>.steps.js`, not in feature files.
|
|
25
25
|
|
|
26
|
+
## My own step is reported as ambiguous. Why?
|
|
27
|
+
|
|
28
|
+
A step of the selector registry takes registered names without quotes:
|
|
29
|
+
`When I click primary button`, `Then I see visible header`. It matches
|
|
30
|
+
any unquoted words after its verb, so a custom step such as
|
|
31
|
+
`When I click next button in tour` matches it too. Quote the argument and
|
|
32
|
+
give the step words of its own (`When I click "Next" in the tour`), or
|
|
33
|
+
start it with other words. See
|
|
34
|
+
[Bare names and your own steps](03-selector-registry.md#bare-names-and-your-own-steps).
|
|
35
|
+
|
|
36
|
+
## How does a custom step that changes the page wait?
|
|
37
|
+
|
|
38
|
+
Call `this.smartSettle()` at its end. It runs the same smart wait the
|
|
39
|
+
built-in action steps run (no request in flight, no pending timer, a DOM
|
|
40
|
+
quiet for 250 ms), for at most 1.5 seconds, or for the budget you pass in
|
|
41
|
+
milliseconds:
|
|
42
|
+
|
|
43
|
+
```js
|
|
44
|
+
const { When } = require('@cucumber/cucumber');
|
|
45
|
+
|
|
46
|
+
When('I add {string} to the cart', async function (item) {
|
|
47
|
+
await this.page.click(`[data-add="${item}"]`);
|
|
48
|
+
await this.smartSettle();
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## How do I add my own helpers to the World?
|
|
53
|
+
|
|
54
|
+
Extend the World of webship-js instead of replacing it: the smart waits,
|
|
55
|
+
the `@mobile` / `@desktop` viewport, video recording and the JavaScript-error
|
|
56
|
+
capture all live in it.
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
const { setWorldConstructor } = require('@cucumber/cucumber');
|
|
60
|
+
const { PlaywrightWorld } = require('webship-js/tests/step-definitions/webship');
|
|
61
|
+
|
|
62
|
+
class ProjectWorld extends PlaywrightWorld {
|
|
63
|
+
async signIn(user) {
|
|
64
|
+
await this.page.goto(`${this.launchUrl}/user/login`);
|
|
65
|
+
// …
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
setWorldConstructor(ProjectWorld);
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
A World set with `setWorldConstructor` that does not extend
|
|
73
|
+
`PlaywrightWorld` keeps none of that; webship-js says so once at the start
|
|
74
|
+
of the run.
|
|
75
|
+
|
|
26
76
|
## Why no `wait 5 seconds` in the example tests?
|
|
27
77
|
|
|
28
78
|
Webship-js installs a smart-settle hook that runs after every
|
|
@@ -55,7 +105,9 @@ HEADLESS=false npm test # same, default slow-mo
|
|
|
55
105
|
```
|
|
56
106
|
|
|
57
107
|
Failed scenarios save a PNG under `screenshots/failed_*.png`. The
|
|
58
|
-
filename embeds the feature, scenario line, and timestamp.
|
|
108
|
+
filename embeds the feature, scenario line, and timestamp. The same
|
|
109
|
+
picture is attached to the failed step in the JSON report, so the HTML
|
|
110
|
+
report shows it under that step.
|
|
59
111
|
|
|
60
112
|
## How do I run a single feature / scenario?
|
|
61
113
|
|
|
@@ -63,6 +115,9 @@ filename embeds the feature, scenario line, and timestamp.
|
|
|
63
115
|
# One feature.
|
|
64
116
|
npx cucumber-js tests/features/login.feature
|
|
65
117
|
|
|
118
|
+
# One scenario, by the line of its Scenario: keyword.
|
|
119
|
+
npx cucumber-js tests/features/login.feature:12
|
|
120
|
+
|
|
66
121
|
# One scenario by name match.
|
|
67
122
|
npx cucumber-js --name "Successful login"
|
|
68
123
|
|
|
@@ -133,6 +188,10 @@ Then I should see "Welcome, Alice" # ✅ user behaviour
|
|
|
133
188
|
Behaviour-tested code is refactor-friendly. Implementation-tested code
|
|
134
189
|
breaks every time the schema changes.
|
|
135
190
|
|
|
191
|
+
## Does `I should see` care about letter case or hidden text?
|
|
192
|
+
|
|
193
|
+
No, and `I should not see` and `eventually I should see` read the page the same way: letter case is ignored, white space is collapsed, and the text of hidden elements counts (the text of `<script>` and `<style>` does not). On a page that reads "Next page", `I should see "next page"` passes and `I should not see "next page"` fails. For the text a visitor can see, with its letter case, use `I wait for the text "Next page" to appear`; for an element, `"<selector>" should be visible`.
|
|
194
|
+
|
|
136
195
|
## How do I name selectors I'll reuse?
|
|
137
196
|
|
|
138
197
|
In `tests/selectors/my-app.json`:
|
|
@@ -215,6 +274,21 @@ Layered approach in [10 Accessibility](10-accessibility.md). Combine
|
|
|
215
274
|
custom probes (heading order, skip link, ARIA validity) with axe-core
|
|
216
275
|
full audits.
|
|
217
276
|
|
|
277
|
+
## Does a passing run mean the HTTPS certificate is valid?
|
|
278
|
+
|
|
279
|
+
No. The scaffold's `playwright.config.ts` opens every browser context with
|
|
280
|
+
`ignoreHTTPSErrors: true` and Chromium with `--ignore-certificate-errors`,
|
|
281
|
+
so a local site with a self-signed certificate can be tested. The same
|
|
282
|
+
settings open a page served with an expired, self-signed or wrong-host
|
|
283
|
+
certificate as if the certificate were valid, and the API and REST steps
|
|
284
|
+
follow them too: a smoke test of a site passes on a broken certificate.
|
|
285
|
+
|
|
286
|
+
To check the certificate, set `ignoreHTTPSErrors: false` in
|
|
287
|
+
`contextOptions` and remove `--ignore-certificate-errors` from the
|
|
288
|
+
Chromium arguments (in a copy of the project kept for that check, if the
|
|
289
|
+
rest of the suite runs against local sites). The first navigation to a page
|
|
290
|
+
with a bad certificate then fails (`net::ERR_CERT_…`).
|
|
291
|
+
|
|
218
292
|
## How do I make CI fast?
|
|
219
293
|
|
|
220
294
|
```bash
|
|
@@ -119,6 +119,8 @@ Scenario: Sort orders by total descending
|
|
|
119
119
|
Then the table "#orders" should be sorted by "Total" in "descending" order
|
|
120
120
|
```
|
|
121
121
|
|
|
122
|
+
A "Total" column of prices (`$1,299.00`, `$49.99`, `$9.99`) is compared as numbers; a column of dates as dates; any other column as text, letter case ignored.
|
|
123
|
+
|
|
122
124
|
## 11. Form file upload
|
|
123
125
|
|
|
124
126
|
```gherkin
|
|
@@ -16,7 +16,8 @@ Keep them consistent across the suite.
|
|
|
16
16
|
| `@perf` | Performance budget (page load, request count). |
|
|
17
17
|
| `@flaky` | Known-unstable. CI retries it once via `--retry` + `--retryTagFilter "@flaky"`. **Never** ship long-term `@flaky` — fix the root cause. |
|
|
18
18
|
| `@wip` | Work in progress. CI excludes with `--tags "not @wip"`. |
|
|
19
|
-
| `@desktop` / `@mobile` | Viewport-locked variants. |
|
|
19
|
+
| `@desktop` / `@mobile` | Viewport-locked variants: the scenario opens at the `desktop` breakpoint (1200 × 900) or the `mobile` breakpoint (375 × 667), or at the sizes `worldParameters.selectors.breakpoints` or `WEBSHIP_SELECTORS_BREAKPOINTS` give those two names; without a `desktop` of the project's own, `@desktop` opens at the breakpoint marked `default: true` (see [Breakpoints](global-settings.md#breakpoints)). `@mobile` wins when both are set. A step can still change the viewport. A mobile lane: `--tags "@mobile"`. |
|
|
20
|
+
| `@touch` | The scenario opens with touch on (`hasTouch`), so `When I tap on "…"` fires the touch events a mobile control listens to; combine it with `@mobile` for a phone. Without it the browser context has no touch and a tap is a click (the step says so once). |
|
|
20
21
|
| `@external` | Hits a third-party service. Skip in offline test runs. |
|
|
21
22
|
| `@auth-setup` | One-shot scenarios that produce auth state files. Run manually after credential rotation. |
|
|
22
23
|
|
|
@@ -55,6 +56,9 @@ npx cucumber-js --tags "not @wip and not @auth-setup"
|
|
|
55
56
|
# Accessibility lane.
|
|
56
57
|
npx cucumber-js --tags "@a11y"
|
|
57
58
|
|
|
59
|
+
# Mobile lane — every @mobile scenario at the mobile breakpoint.
|
|
60
|
+
npx cucumber-js --tags "@mobile"
|
|
61
|
+
|
|
58
62
|
# Flaky lane — separate report, allowed to fail without blocking.
|
|
59
63
|
npx cucumber-js --tags "@flaky" --retry 2
|
|
60
64
|
|