webship-js 2.0.11 → 2.0.13

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.
Files changed (175) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/workflows/github-actions.yml +48 -0
  4. package/.gitlab-ci.yml +9 -4
  5. package/.harness/webship-js-pipeline.yml +5 -6
  6. package/.semaphore/semaphore.yml +6 -9
  7. package/.teamcity/settings.kts +7 -6
  8. package/.travis.yml +6 -1
  9. package/AGENTS.md +1 -1
  10. package/CLAUDE.md +65 -23
  11. package/Jenkinsfile +5 -3
  12. package/azure-pipelines.yml +17 -8
  13. package/bamboo-specs/bamboo.yml +9 -15
  14. package/bin/init-webship.js +53 -10
  15. package/bitbucket-pipelines.yml +5 -1
  16. package/buildspec.yml +6 -7
  17. package/cloudbuild.yaml +28 -12
  18. package/codefresh.yml +6 -6
  19. package/cucumber.js +17 -10
  20. package/docs/00-quick-start.md +8 -0
  21. package/docs/02-bbr-smart-waits.md +15 -10
  22. package/docs/03-selector-registry.md +24 -0
  23. package/docs/04-step-reference.md +51 -25
  24. package/docs/05-web-first-assertions.md +6 -0
  25. package/docs/07-auth-state.md +1 -1
  26. package/docs/08-clock-mocking.md +21 -2
  27. package/docs/09-api-testing.md +40 -2
  28. package/docs/10-accessibility.md +2 -0
  29. package/docs/11-debugging.md +3 -1
  30. package/docs/12-ai-agent-guide.md +5 -0
  31. package/docs/13-faq.md +72 -1
  32. package/docs/14-recipes-cookbook.md +2 -0
  33. package/docs/15-tag-conventions.md +2 -1
  34. package/docs/16-ci-cd.md +140 -119
  35. package/docs/README.md +5 -5
  36. package/docs/advanced-screenshots.md +3 -1
  37. package/docs/api-step-definitions.md +16 -2
  38. package/docs/global-settings.md +69 -17
  39. package/docs/install-webship-js.md +2 -0
  40. package/docs/step-definitions/then-i-should-see.md +14 -1
  41. package/docs/step-definitions/then-item-checkbox.md +2 -0
  42. package/docs/step-definitions/when-i-fill.md +4 -0
  43. package/docs/step-definitions/when-i-select-option-select-list.md +2 -0
  44. package/examples/check-switch.html +37 -0
  45. package/examples/choice-controls.html +29 -0
  46. package/examples/click-whitespace.html +37 -0
  47. package/examples/datetime-fields.html +52 -0
  48. package/examples/element-selector-hint.html +16 -0
  49. package/examples/field-states.html +27 -0
  50. package/examples/fill-in-empty.html +26 -0
  51. package/examples/fill-unreachable.html +27 -0
  52. package/examples/follow-hidden-first.html +29 -0
  53. package/examples/iframe-inner.html +20 -0
  54. package/examples/iframe-nested.html +16 -0
  55. package/examples/iframe-outer.html +15 -0
  56. package/examples/multi-value-fields.html +54 -0
  57. package/examples/registered-names.html +15 -0
  58. package/examples/select-by-label.html +33 -0
  59. package/examples/settle-budget.html +21 -0
  60. package/examples/sorted-tables.html +38 -0
  61. package/examples/text-matching.html +48 -0
  62. package/examples/text-order.html +25 -0
  63. package/examples/touch.html +22 -0
  64. package/examples/viewport-top.html +36 -0
  65. package/package.json +17 -1
  66. package/playwright.config.ts +3 -1
  67. package/tests/check-api-launch-url.js +106 -0
  68. package/tests/check-assets.js +103 -0
  69. package/tests/check-attachments.js +105 -0
  70. package/tests/check-breakpoints.js +117 -0
  71. package/tests/check-clock.js +143 -0
  72. package/tests/check-config.js +90 -0
  73. package/tests/check-context.js +215 -0
  74. package/tests/check-dry-run.js +104 -0
  75. package/tests/check-examples.js +10 -4
  76. package/tests/check-exit-report.js +141 -0
  77. package/tests/check-javascript-errors.js +105 -0
  78. package/tests/check-must-fail.js +5 -4
  79. package/tests/check-network-changed.js +137 -0
  80. package/tests/check-scaffold.js +54 -2
  81. package/tests/check-screenshots.js +117 -0
  82. package/tests/check-settle-verbs.js +137 -0
  83. package/tests/check-time-limit.js +104 -0
  84. package/tests/check-video.js +156 -0
  85. package/tests/check-world.js +167 -0
  86. package/tests/features/api-base-url.feature +25 -0
  87. package/tests/features/api-form-data.feature +18 -0
  88. package/tests/features/api-json-paths.feature +24 -0
  89. package/tests/features/api-response-contains.feature +21 -0
  90. package/tests/features/api-response-header-presence.feature +17 -0
  91. package/tests/features/api-response-header.feature +17 -0
  92. package/tests/features/api-saved-placeholders.feature +37 -0
  93. package/tests/features/api-step-definitions-individual.feature +1 -1
  94. package/tests/features/api-tables.feature +40 -0
  95. package/tests/features/breakpoints.feature +25 -0
  96. package/tests/features/check-switch.feature +28 -0
  97. package/tests/features/choice-controls.feature +35 -0
  98. package/tests/features/click-whitespace.feature +29 -0
  99. package/tests/features/complete-api-testing-examples.feature +1 -1
  100. package/tests/features/datetime-field-lookup.feature +29 -0
  101. package/tests/features/element-selector-hint.feature +14 -0
  102. package/tests/features/field-state.feature +21 -0
  103. package/tests/features/fill-in-empty-value.feature +41 -0
  104. package/tests/features/fill-reachable.feature +13 -0
  105. package/tests/features/follow-hidden-first.feature +9 -0
  106. package/tests/features/iframe-nested.feature +43 -0
  107. package/tests/features/javascript-tolerated-errors.feature +20 -0
  108. package/tests/features/modal-open.feature +13 -0
  109. package/tests/features/multi-value-field-lookup.feature +30 -0
  110. package/tests/features/registered-names.feature +14 -0
  111. package/tests/features/select-by-label.feature +31 -0
  112. package/tests/features/selector-files.feature +14 -0
  113. package/tests/features/selectors-table-header.feature +35 -0
  114. package/tests/features/settle-budget.feature +11 -0
  115. package/tests/features/sorted-tables.feature +19 -0
  116. package/tests/features/storage-quoted-values.feature +26 -0
  117. package/tests/features/text-matching.feature +38 -0
  118. package/tests/features/text-order.feature +14 -0
  119. package/tests/features/touch.feature +21 -0
  120. package/tests/features/viewport-top.feature +13 -0
  121. package/tests/features/xml-namespaces.feature +34 -0
  122. package/tests/must-fail/api-json-paths.feature +21 -0
  123. package/tests/must-fail/api-response-contains.feature +23 -0
  124. package/tests/must-fail/api-response-header-presence.feature +17 -0
  125. package/tests/must-fail/api-response-header.feature +21 -0
  126. package/tests/must-fail/api-without-base-url.feature +11 -0
  127. package/tests/must-fail/breakpoints.feature +15 -0
  128. package/tests/must-fail/choice-controls.feature +25 -0
  129. package/tests/must-fail/clock.feature +11 -0
  130. package/tests/must-fail/datetime-field.feature +10 -0
  131. package/tests/must-fail/element-selector-hint.feature +17 -0
  132. package/tests/must-fail/field-state.feature +20 -0
  133. package/tests/must-fail/fill-field.feature +30 -0
  134. package/tests/must-fail/iframe-text.feature +17 -0
  135. package/tests/must-fail/modal-open.feature +26 -0
  136. package/tests/must-fail/multi-value-field.feature +18 -0
  137. package/tests/must-fail/registered-names.feature +25 -0
  138. package/tests/must-fail/select-list.feature +15 -0
  139. package/tests/must-fail/selector-files.feature +10 -0
  140. package/tests/must-fail/sorted-tables.feature +20 -0
  141. package/tests/must-fail/storage-before-a-page.feature +13 -0
  142. package/tests/must-fail/text-matching.feature +16 -0
  143. package/tests/must-fail/text-order.feature +15 -0
  144. package/tests/must-fail/viewport-top.feature +20 -0
  145. package/tests/must-fail/yaml-numbers.feature +48 -0
  146. package/tests/step-definitions/a11y.steps.js +24 -15
  147. package/tests/step-definitions/action.steps.js +53 -20
  148. package/tests/step-definitions/api.steps.js +349 -67
  149. package/tests/step-definitions/assertion.steps.js +100 -10
  150. package/tests/step-definitions/auth.steps.js +15 -18
  151. package/tests/step-definitions/clock.steps.js +22 -0
  152. package/tests/step-definitions/debug.steps.js +8 -0
  153. package/tests/step-definitions/dialog.steps.js +7 -0
  154. package/tests/step-definitions/element.steps.js +132 -17
  155. package/tests/step-definitions/field.steps.js +412 -96
  156. package/tests/step-definitions/form.steps.js +88 -37
  157. package/tests/step-definitions/iframe.steps.js +89 -29
  158. package/tests/step-definitions/input.steps.js +26 -7
  159. package/tests/step-definitions/javascript.steps.js +64 -22
  160. package/tests/step-definitions/modal.steps.js +79 -13
  161. package/tests/step-definitions/navigation.steps.js +14 -0
  162. package/tests/step-definitions/network.steps.js +15 -5
  163. package/tests/step-definitions/response.steps.js +6 -4
  164. package/tests/step-definitions/responsive.steps.js +26 -33
  165. package/tests/step-definitions/screenshot.steps.js +25 -8
  166. package/tests/step-definitions/scroll.steps.js +20 -0
  167. package/tests/step-definitions/selectors.steps.js +95 -48
  168. package/tests/step-definitions/storage.steps.js +38 -13
  169. package/tests/step-definitions/table.steps.js +81 -6
  170. package/tests/step-definitions/video.steps.js +52 -55
  171. package/tests/step-definitions/wait.steps.js +88 -23
  172. package/tests/step-definitions/web-first.steps.js +69 -35
  173. package/tests/step-definitions/webship.js +741 -145
  174. package/tests/step-definitions/xml.steps.js +49 -15
  175. package/tests/step-definitions/yaml.steps.js +45 -20
package/docs/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Webship-js is a BDD-first browser-automation harness built on Playwright + Cucumber-js. Feature files in plain Gherkin; selectors that survive redesigns; smart waits that never sleep.
4
4
 
5
- **417 built-in steps** across **36 step files**. **288 example scenarios / 1,406 step executions** in the bundled suite, all green on chromium, firefox, and webkit.
5
+ **428 built-in steps** across **36 step files**. **580 example scenarios / 2,868 step executions** in the bundled suite, all green in the CI run on Chromium.
6
6
 
7
7
  ## Reading order
8
8
 
@@ -76,15 +76,15 @@ webship-js/
76
76
  │ ├── webship.js # World setup, hooks, shared helpers (smartSettle, modal, selectors, date tokens)
77
77
  │ ├── a11y.steps.js (30) # axe-core audits + WCAG hygiene probes
78
78
  │ ├── action.steps.js (7) # press / click / follow / attach
79
- │ ├── api.steps.js (22) # REST long form (base URL, headers, query, body, JSON Pointer)
79
+ │ ├── api.steps.js (24) # REST long form (base URL, headers, query, body, JSON Pointer)
80
80
  │ ├── assertion.steps.js (14) # see / not see, in row, in element, response, count
81
81
  │ ├── auth.steps.js (3) # save / restore / clear storageState
82
82
  │ ├── clock.steps.js (7) # install / advance / pause / set system time
83
83
  │ ├── cookie.steps.js (12) # cookie exists / equals / contains
84
84
  │ ├── debug.steps.js (2) # print URL / last response (diagnostic)
85
85
  │ ├── dialog.steps.js (8) # native alert / confirm / prompt
86
- │ ├── element.steps.js (19) # focus / scroll-to / dispatch / count / position
87
- │ ├── field.steps.js (27) # field state, checkbox, radio, select-list
86
+ │ ├── element.steps.js (20) # focus / scroll-to / dispatch / count / position
87
+ │ ├── field.steps.js (35) # field state, checkbox, radio, select-list
88
88
  │ ├── file-download.steps.js (8) # capture + assert filename / mime / path
89
89
  │ ├── form.steps.js (13) # fill / select / check / uncheck / radio
90
90
  │ ├── iframe.steps.js (10) # frameLocator switch + scoped click / fill / assert
@@ -102,7 +102,7 @@ webship-js/
102
102
  │ ├── rest.steps.js (5) # REST short form
103
103
  │ ├── screenshot.steps.js (6) # manual + auto-on-failure + per-step capture
104
104
  │ ├── scroll.steps.js (12) # page + scoped element scroll
105
- │ ├── selectors.steps.js (22) # named CSS / XPath registry + 22 CMS / framework presets
105
+ │ ├── selectors.steps.js (24) # named CSS / XPath registry + 22 CMS / framework presets
106
106
  │ ├── storage.steps.js (9) # local / session storage
107
107
  │ ├── table.steps.js (8) # data-table row / column assertions
108
108
  │ ├── video.steps.js (4) # start / stop / save webm recording
@@ -8,11 +8,13 @@ This documentation page covers screenshot capture functionality in Webship JS 2.
8
8
  ## Key Features
9
9
 
10
10
  **Auto-capture hooks** activate screenshots in two scenarios:
11
- - On failed steps (with `failedPrefix` prepended)
11
+ - On failed steps (with `failedPrefix` prepended); the screenshot of a failed step is also attached to that step in the JSON report, so the HTML report shows it
12
12
  - On every step when scenarios are tagged `@screenshots`
13
13
 
14
14
  **Filename tokens** can be used in `with name "..."` steps or configuration keys like `filenamePattern` and `filenamePatternFailed`.
15
15
 
16
+ A named screenshot writes `<name>.png` and `<name>.html`. A name that already ends with `.png`, `.jpg`, `.jpeg` or `.html` keeps that one extension: `with name "homepage.png"` writes `homepage.png` and `homepage.html`.
17
+
16
18
  ## Configuration
17
19
 
18
20
  Settings reside in `cucumber.js` under `worldParameters.screenshot`. Each key accepts environment variable overrides:
@@ -19,6 +19,11 @@ login for example, use the short-form REST steps
19
19
  (`When I send a REST "GET" request to "/api/me"`), which go through the
20
20
  browser context.
21
21
 
22
+ The base URL (`Given the API base URL is "url"`) is reset before every
23
+ scenario, like the headers and the body: set it in each scenario or in a
24
+ `Background`. A path is joined to the launch URL of the run, and a request
25
+ step given a whole URL sends it as written.
26
+
22
27
  ## Available API Step Definitions
23
28
 
24
29
  The documentation lists 22 distinct step definition categories:
@@ -31,6 +36,7 @@ The documentation lists 22 distinct step definition categories:
31
36
 
32
37
  **Request Configuration:**
33
38
  - Given I set placeholder "{{placeholder}}" to "value"
39
+ - When I save the JSON property "propertyPath" as placeholder "{{placeholder}}"
34
40
  - Given I set the request body to 'JSON-data'
35
41
  - Given I set the request body with
36
42
  - Given the API base URL is "url"
@@ -47,10 +53,18 @@ The documentation lists 22 distinct step definition categories:
47
53
  - Then the API response should contain "text"
48
54
  - Then the API response should contain json
49
55
  - Then the API response should not contain "text"
56
+ - Then the API response should contain the header "header name"
57
+ - Then the API response should not contain the header "header name"
50
58
  - Then the response should be valid JSON
51
- - Then the response header "response header" should be "value"
59
+ - Then the response header "response header" should be "value" (the whole value)
60
+ - Then the response header "response header" should contain "part" (a part of the value)
61
+
62
+ The two text checks (`should contain "text"`, `should not contain "text"`)
63
+ ignore letter case and replace placeholders in the text first, so the
64
+ negative check fails on any text the positive one finds.
52
65
 
53
- **JSON Response Validation:**
66
+ **JSON Response Validation** (a property is named by a dot path,
67
+ `data.0.id` or `data[0].id`, or a JSON Pointer, `/data/0/id`):
54
68
  - Then the JSON response should have "propertyPath" equal to "value"
55
69
  - Then the JSON response should have property "propertyPath"
56
70
  - Then the JSON response should not have property "propertyPath"
@@ -46,9 +46,12 @@ Base URL prepended to every relative path in `Given I am on "/path"`. An absolut
46
46
 
47
47
  ### `assetsFolder`
48
48
 
49
- Resolved automatically to `tests/assets/`. Used by `When I attach the
50
- file "...".`. Override per-World by extending the world constructor;
51
- no env var.
49
+ The `tests/assets/` folder of the project. `When I attach the file "…" to
50
+ "…"`, the XML and YAML file steps and the YAML schema and diff steps look
51
+ for a file name there first, then as written from the project root
52
+ (`tests/schemas/openapi.json`), then in the package's own `tests/assets/`;
53
+ a file found in none of them fails with the paths tried. Override
54
+ per-World by extending the world constructor; no env var.
52
55
 
53
56
  ### `minWaitTime` — pacing knobs
54
57
 
@@ -62,6 +65,9 @@ minWaitTime: {
62
65
  }
63
66
  ```
64
67
 
68
+ Every key is optional, and so is the block: a key left out keeps the
69
+ default below.
70
+
65
71
  | Key | Default | Purpose |
66
72
  | --- | --- | --- |
67
73
  | `page` | `3000` | Per-navigation budget for `smartSettle`. Bump for slow CI. |
@@ -76,14 +82,15 @@ minWaitTime: {
76
82
 
77
83
  ### `selectors` — named selector registry
78
84
 
85
+ A selector file of `files` is looked for in the `filesPath` folder first (default `./tests/selectors/`), then as written from the project root, so `'auth.json'` and `'tests/selectors/auth.json'` name the same file.
86
+
79
87
  ```js
80
88
  selectors: {
81
89
  css: { /* name → CSS selector */ },
82
90
  xpath: { /* name → XPath expression */ },
83
91
  filesPath: './tests/selectors/', // base path for JSON presets
84
92
  files: [], // JSON files to auto-load per scenario
85
- offset: 60, // px — scroll offset for relative-position assertions
86
- breakpoints: { // viewport sizes (the viewing-the-site steps; add `mobile` / `desktop` to size the @mobile / @desktop tags)
93
+ breakpoints: { // named viewport sizes — see "Breakpoints" below
87
94
  xs: { width: 375, height: 667 },
88
95
  sm: { width: 576, height: 800 },
89
96
  md: { width: 768, height: 1024 },
@@ -101,8 +108,31 @@ selectors: {
101
108
  | `xpath` | `{}` | — |
102
109
  | `filesPath` | `./tests/selectors/` | — |
103
110
  | `files` | `[]` | — |
104
- | `offset` | `60` | `WEBSHIP_SELECTORS_OFFSET` |
105
- | `breakpoints` | xs..xxxl | `WEBSHIP_SELECTORS_BREAKPOINTS` (JSON string) |
111
+ | `breakpoints` | xs..xxxl, mobile, tablet, desktop | `WEBSHIP_SELECTORS_BREAKPOINTS` (JSON object, merged over the config) |
112
+
113
+ #### Breakpoints
114
+
115
+ One registry of named viewport sizes serves every step and tag that names a
116
+ size: `Given I am viewing the site on a "md" screen`, `When I set the
117
+ viewport to the "tablet" breakpoint`, and the `@mobile` / `@desktop` tags.
118
+ The names are looked up in this order, each source replacing the sizes of
119
+ the names it gives and keeping all the others:
120
+
121
+ 1. The built-in names: `xs` 375 × 667, `sm` 576 × 800, `md` 768 × 1024,
122
+ `lg` 992 × 768, `xl` 1200 × 900, `xxl` 1400 × 900, `xxxl` 1920 × 1080,
123
+ `mobile` 375 × 667, `tablet` 768 × 1024, `desktop` 1200 × 900.
124
+ 2. `worldParameters.selectors.breakpoints`.
125
+ 3. `WEBSHIP_SELECTORS_BREAKPOINTS`, a JSON object of named sizes, for
126
+ example `WEBSHIP_SELECTORS_BREAKPOINTS='{"tablet":{"width":800,"height":1280}}'`.
127
+ A value that is not a JSON object is reported once and ignored.
128
+ 4. The names a scenario adds with `Given the following responsive breakpoints:`.
129
+
130
+ `@mobile` opens the scenario at the `mobile` size and `@desktop` at the
131
+ `desktop` size. When the project gives no `desktop` of its own, `desktop`
132
+ is the breakpoint marked `default: true` (`xl` in the scaffold), so moving
133
+ the mark moves the `@desktop` size. Without either tag the viewport stays
134
+ fluid (`contextOptions.viewport` of `playwright.config.ts`). An unknown name
135
+ fails with the list of the known ones.
106
136
 
107
137
  ### `screenshot` — capture configuration
108
138
 
@@ -144,7 +174,7 @@ Filename pattern tokens: `{datetime}`, `{date}`, `{time}`, `{feature_file}`,
144
174
  video: {
145
175
  mode: 'off', // WEBSHIP_VIDEO — 'off' | 'on' | 'on-failure' | 'tag'
146
176
  dir: './videos', // WEBSHIP_VIDEO_DIR
147
- size: { width: 1280, height: 720 }, // recording viewport
177
+ size: { width: 1280, height: 720 }, // WEBSHIP_VIDEO_SIZE ("1280x720")
148
178
  filenamePattern: '{datetime}.{feature_file}.{scenario}.{status}.{ext}',
149
179
  }
150
180
  ```
@@ -153,19 +183,31 @@ Tag overrides per scenario:
153
183
 
154
184
  | Tag | Effect |
155
185
  | --- | --- |
156
- | `@video` | Force recording on. |
186
+ | `@video` | Force recording on, in every mode. |
157
187
  | `@no-video` | Suppress recording. |
158
188
 
159
189
  Modes:
160
190
 
161
191
  | Mode | Behaviour |
162
192
  | --- | --- |
163
- | `off` (default) | No recording. |
193
+ | `off` (default) | No recording, except the scenarios tagged `@video`. |
164
194
  | `on` | Record every scenario. |
165
- | `on-failure` | Record every scenario, keep only failures. |
166
- | `tag` | Record only scenarios tagged `@video`. |
167
-
168
- Mid-scenario start / stop steps live in `video.steps.js`. Recording starts at context creation only — `When I start video recording` closes + reopens the context, losing page state. Call before any navigation.
195
+ | `on-failure` | Record every scenario, keep only failures — and the videos of `@video` scenarios or with a name reserved by `I save the current video as "…"`. |
196
+ | `tag` | The same as `off`: only the scenarios tagged `@video` record. |
197
+
198
+ A video is saved under `filenamePattern` (default
199
+ `{datetime}.{feature_file}.{scenario}.{status}.{ext}`) when the scenario
200
+ ends: `{datetime}` is when the recording started, `{status}` the result of
201
+ the scenario in lower case (`passed`, `failed`, …), so
202
+ `videos/*.failed.webm` lists the videos of the failures. A recording that
203
+ `When I stop video recording` ends is saved with the status `manual`, and a
204
+ name reserved with `When I save the current video as "…"` wins over the
205
+ pattern. `Then print video path` prints that final path (with `<status>`
206
+ standing for the result still to come), never Playwright's temporary file.
207
+ `When I start video recording` on a scenario that already records changes
208
+ nothing.
209
+
210
+ Mid-scenario start / stop steps live in `video.steps.js`. Recording starts at context creation only — `When I start video recording` opens a new browser context: the cookies and local storage, the viewport, the smart waits, JavaScript-error capture and a running request log go on, the page starts blank. Call it before any navigation.
169
211
 
170
212
  ### `javascript` — page-error / console capture
171
213
 
@@ -212,20 +254,30 @@ const config = {
212
254
  | --- | --- | --- |
213
255
  | `browser` | `chromium` | `BROWSER` (`chromium` / `firefox` / `webkit`) |
214
256
  | `launchOptions.headless` | `true` | `HEADLESS=false` for headed |
215
- | `launchOptions.slowMo` | `300` headed: `800` | `SLOW_MO` (ms) |
257
+ | `launchOptions.slowMo` | `300` headed: `800`, on a laptop and in CI alike | `SLOW_MO` (ms); `SLOW_MO=0` for full speed |
216
258
  | `launchOptions.args` | chromium-only flags | edit file directly |
217
259
  | `contextOptions.viewport` | `null` (use browser default) | edit file directly |
218
260
  | `contextOptions.ignoreHTTPSErrors` | `true` | edit file directly |
219
261
 
262
+ `ignoreHTTPSErrors: true` and Chromium's `--ignore-certificate-errors` let a
263
+ suite run against a local site with a self-signed certificate. They also open
264
+ a page served with an expired, self-signed or wrong-host certificate as if
265
+ the certificate were valid, and the API and REST steps follow the same
266
+ setting: a passing run says nothing about the certificate. To check it, set
267
+ `ignoreHTTPSErrors: false` and remove `--ignore-certificate-errors` from the
268
+ Chromium arguments; the first navigation to a page with a bad certificate
269
+ then fails.
270
+
220
271
  ---
221
272
 
222
273
  ## Behaviour toggles
223
274
 
224
275
  | Env var | Effect |
225
276
  | --- | --- |
226
- | `WEBSHIP_AUTO_SETTLE` | Set to `off` to disable the BBR auto-settle hook (`smartSettle(page, 1500)` after every state-changing step). |
227
- | `WEBSHIP_STEP_TIMEOUT` | Cucumber step timeout in milliseconds. Defaults to `45000`. webship-js calls `setDefaultTimeout()` when its step definitions load, which overrides a `timeout` set in your own `cucumber.js`, so raise it here instead. |
277
+ | `WEBSHIP_AUTO_SETTLE` | Set to `off` to disable the BBR auto-settle hook (`smartSettle(page, 1500)` after every state-changing step; see [BBR smart waits](02-bbr-smart-waits.md#auto-settle-after-actions) for the verbs). |
278
+ | `WEBSHIP_STEP_TIMEOUT` | Cucumber step timeout in milliseconds. Defaults to `45000`. webship-js calls `setDefaultTimeout()` when its step definitions load, which overrides a `timeout` set in your own `cucumber.js`, so raise it here instead. A step whose length the scenario gives (`I wait 2 minutes`, `… within 60 seconds`) is not cut by it: it runs for that length, and gives up 15 seconds past it on a page that stopped answering. |
228
279
  | `WEBSHIP_REPORT_DISABLE` | Set to `1` to skip auto-generating the HTML report on cucumber-js process exit. |
280
+ | `WEBSHIP_REPORT_JSON` | The JSON report the HTML report is built from at the end of a run. Without it, the file of the `json:` formatter of the command line or of `cucumber.js` is used, else `tests/reports/cucumber_report.json`. With `--parallel`, the report is built once, after the whole JSON report is written. |
229
281
  | `WEBSHIP_REPORT_ARGS` | Extra CLI flags forwarded to `bin/generate-reports.js`. e.g. `--theme hierarchy --layout 2`. |
230
282
 
231
283
  ---
@@ -15,6 +15,8 @@ npx init-webship-js
15
15
 
16
16
  `npm install-scripts approve webship-js` lets the install script run on the next installs.
17
17
 
18
+ A project upgraded from webship-js 1.x has a `test` script that runs Nightwatch: the scaffold replaces it with the cucumber-js suite, keeps the old command as `npm run test:nightwatch`, and says so. `npx init-webship-js --force` rewrites the scaffold's files and scripts, but never `tests/step-definitions/custom.js`, which holds the project's own steps.
19
+
18
20
  ## Automated Functional Acceptance Testing
19
21
 
20
22
  The starter feature opens the home page of your site:
@@ -22,11 +22,24 @@ The following step variations are available:
22
22
  - Then I should see "value" in the "text" element by attr
23
23
  - Then I should not see "value" in the "text" element by attr
24
24
 
25
+ ## Reading the page text
26
+
27
+ `I should see "text"`, `I should not see "text"` and `eventually I should see "text"` read the page the same way: the text of the page as Playwright's text matching reads it.
28
+
29
+ - Letter case is ignored: on a page that reads "Next page", `I should see "next page"` passes and `I should not see "next page"` fails.
30
+ - Runs of white space are collapsed, so a line the markup wraps still matches.
31
+ - The text of hidden elements counts; the text of `<script>`, `<noscript>` and `<style>` does not.
32
+ - The value of a field, the text of an image and the content of an iframe are not page text.
33
+
34
+ `I should see` waits up to 5 seconds for the text to come, `I should not see` up to 5 seconds for it to go, and `eventually I should see` up to 10 seconds, or the "within N seconds" it is given.
35
+
36
+ For the text a visitor can see, with its letter case, use `I wait for the text "text" to appear` or `I wait for the text "text" to disappear`; for an element, `"<selector>" should be visible` or `"<selector>" should not be visible`.
37
+
25
38
  ## Seeing an element
26
39
 
27
40
  `I should see (a/an) "text" element` and `I should not see (a/an) "text" element` name the element by its exact visible text, as it reads on the page. A `<label for="...">` stands for the control it labels. "Should not see" is the opposite of "should see": it passes when no element named that way is visible, so an element that is hidden does not fail it.
28
41
 
29
- The text is not a CSS selector. For a selector use `"<selector>" should be visible` or `"<selector>" should not be visible`.
42
+ The text is not a CSS selector. For a selector use `"<selector>" should be visible` or `"<selector>" should not be visible`. When the argument looks like a selector (`.news-item`, `#main`, `[data-testid=card]`, `div.card`, or a bare tag name such as `header`), a failure of `I should see a "…" element` says so and names the selector step, and `I should not see a "…" element` prints a warning when it passes while that selector matches a visible element: it checked a text, not the selector.
30
43
 
31
44
  ## Purpose
32
45
 
@@ -5,6 +5,8 @@
5
5
 
6
6
  This step definition validates whether a checkbox associated with a specified item is in a checked or unchecked state. It serves to confirm expected checkbox behavior during automated testing.
7
7
 
8
+ The "item" is a CSS selector (`#privacy-policy`, `input[name=newsletter]`), the exact text of the checkbox's label, its name, its id or its value. A checkbox that is not found within 5 seconds fails the step with what was looked for, the page and a hint; a wrong state fails with `The checkbox "…" is not checked.` or `… is checked, but it should not be.`
9
+
8
10
  ## Related Step Definitions
9
11
 
10
12
  The following variations of this step are available:
@@ -18,6 +18,10 @@
18
18
 
19
19
  Each variant supports different approaches to locating form elements—whether by label text, CSS selectors, or HTML attributes—and accommodates both single-field and multi-field input scenarios.
20
20
 
21
+ A field that is hidden, disabled or read-only cannot be filled: the step fails within 5 seconds and says which of the three it is (`The field "Hidden note" is on the page but hidden, so it cannot be filled.`), with the page and a hint; a field named by attribute that is not on the page fails within 5 seconds too.
22
+
23
+ An empty value empties the field in every form of the step: `When I fill in "Title" with ""`, `When I fill in "" for "Title"`, `When I fill in "#title" with "" by attr`, or an empty cell in the table of `I fill in the following:`.
24
+
21
25
  ## More examples
22
26
 
23
27
  <!-- generated: extended-examples -->
@@ -11,6 +11,8 @@ When (I|we)* select "([^"]*)?" from "([^"]*)?"
11
11
 
12
12
  "This step definition acts as a command to select an option from a dropdown list." The mechanism identifies a select element by its associated label, then selects the matching option based on its displayed text.
13
13
 
14
+ The select list is named by the exact text of its label (one word or several), else by its name, else by its id; a name that starts with `#`, `.` or `[` is a CSS selector. The option is named by its text, else by its value. When no select list is found within 5 seconds, or the list has no such option, the step fails at once and lists the options the list has.
15
+
14
16
  ## Example
15
17
 
16
18
  **Selection by label:**
@@ -0,0 +1,37 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Toggle switches and custom checkboxes | Webship-js</title>
6
+ <style>
7
+ /* A toggle switch as cookie consent dialogs draw it: the checkbox is an
8
+ invisible input, and the slider of its label lies on top of it. */
9
+ .switch { position: relative; display: block; height: 30px; margin: 12px 0; }
10
+ .switch input { position: absolute; top: 0; left: 0; opacity: 0; width: 50px; height: 30px; margin: 0; }
11
+ .switch .slider { position: absolute; top: 0; left: 0; width: 50px; height: 30px; background: #ccc; border-radius: 15px; }
12
+ .switch input:checked + label .slider { background: #2a7; }
13
+ .switch .title { margin-left: 60px; line-height: 30px; }
14
+ /* A custom checkbox: the input is not displayed, its label draws the box. */
15
+ .custom input { display: none; }
16
+ .custom label::before { content: ""; display: inline-block; width: 16px; height: 16px; margin-right: 8px; border: 1px solid #333; }
17
+ .custom input:checked + label::before { background: #333; }
18
+ </style>
19
+ </head>
20
+ <body>
21
+ <main>
22
+ <h1>Toggle switches and custom checkboxes</h1>
23
+ <div class="switch">
24
+ <input id="analytics" type="checkbox" aria-labelledby="analytics-title">
25
+ <label for="analytics"><span class="slider"></span><span id="analytics-title" class="title">Analytics cookies</span></label>
26
+ </div>
27
+ <div class="switch">
28
+ <input id="marketing" type="checkbox" aria-labelledby="marketing-title" checked>
29
+ <label for="marketing"><span class="slider"></span><span id="marketing-title" class="title">Marketing cookies</span></label>
30
+ </div>
31
+ <div class="custom">
32
+ <input id="remember" type="checkbox">
33
+ <label for="remember">Remember this device</label>
34
+ </div>
35
+ </main>
36
+ </body>
37
+ </html>
@@ -0,0 +1,29 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Checkboxes, radio buttons and fields named by label, name or id</title>
6
+ <style>
7
+ body { font-family: Arial, sans-serif; padding: 20px; }
8
+ p, fieldset { margin: 10px 0; }
9
+ </style>
10
+ </head>
11
+ <body>
12
+ <h1>Checkboxes, radio buttons and fields</h1>
13
+ <form id="choices">
14
+ <p><label><input type="checkbox" id="opt-news" name="newsletter" checked> Newsletter</label></p>
15
+ <p>
16
+ <input type="hidden" name="terms" value="0">
17
+ <input type="checkbox" id="opt-terms" name="terms" value="1">
18
+ <label for="opt-terms">Accept the terms</label>
19
+ </p>
20
+ <fieldset>
21
+ <legend>Plan</legend>
22
+ <label><input type="radio" name="plan" value="basic" id="plan-basic"> Basic</label>
23
+ <label><input type="radio" name="plan" value="premium" id="plan-premium" checked> Premium</label>
24
+ </fieldset>
25
+ <p><label for="city">City</label> <input id="city" name="city_name" type="text"></p>
26
+ <p><input type="text" name="nickname" id="nick" aria-label="Nick"></p>
27
+ </form>
28
+ </body>
29
+ </html>
@@ -0,0 +1,37 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Links and buttons with white space around their text | Webship-js</title>
6
+ </head>
7
+ <body>
8
+ <!-- The way menu templates print their links: the text on a line of its own,
9
+ inside a span, with the indentation of the template around it. -->
10
+ <nav aria-label="Main">
11
+ <ul>
12
+ <li><a href="#products">
13
+ <span class="inner">Products</span>
14
+ </a></li>
15
+ <li><a href="#about-us">About
16
+ us</a></li>
17
+ </ul>
18
+ </nav>
19
+ <main>
20
+ <h1>Links and buttons with white space around their text</h1>
21
+ <button type="button" id="save-draft" onclick="document.getElementById('result').textContent = 'The draft was saved.'">
22
+ Save draft
23
+ </button>
24
+ <table>
25
+ <tbody>
26
+ <tr>
27
+ <td>Order 1042</td>
28
+ <td><a href="#order-1042">
29
+ Edit
30
+ </a></td>
31
+ </tr>
32
+ </tbody>
33
+ </table>
34
+ <p id="result"></p>
35
+ </main>
36
+ </body>
37
+ </html>
@@ -0,0 +1,52 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Datetime fields side by side</title>
6
+ <style>
7
+ body { font-family: Arial, sans-serif; padding: 20px; }
8
+ label { margin-right: 6px; }
9
+ p, div { margin: 10px 0; }
10
+ </style>
11
+ </head>
12
+ <body>
13
+ <h1>Datetime fields side by side</h1>
14
+ <form id="schedule">
15
+ <p>A label whose text contains the text of the next one:</p>
16
+ <div class="form-item">
17
+ <label for="restart-date">Restart date</label>
18
+ <input type="date" id="restart-date" name="restart_date">
19
+ </div>
20
+ <div class="form-item">
21
+ <label for="start-date">Start</label>
22
+ <input type="date" id="start-date" name="begin_date">
23
+ <input type="time" id="start-time" name="begin_time">
24
+ </div>
25
+
26
+ <p>Two fields in one paragraph; the first has a date only:</p>
27
+ <p class="flat">
28
+ <label for="opening-date">Opening</label>
29
+ <input type="date" id="opening-date" name="opening_day">
30
+ <label for="closing-date">Closing</label>
31
+ <input type="date" id="closing-date" name="closing_day">
32
+ <input type="time" id="closing-time" name="closing_hour">
33
+ </p>
34
+
35
+ <p>A label alone in its wrapper, the inputs in the next one:</p>
36
+ <div class="field">
37
+ <div class="field-label"><label>Arrival</label></div>
38
+ <div class="field-inputs">
39
+ <input type="date" id="arrival-date" name="field_a_date">
40
+ <input type="time" id="arrival-time" name="field_a_time">
41
+ </div>
42
+ </div>
43
+ <div class="field">
44
+ <div class="field-label"><label>Leaving</label></div>
45
+ <div class="field-inputs">
46
+ <input type="date" id="leaving-date" name="field_l_date">
47
+ <input type="time" id="leaving-time" name="field_l_time">
48
+ </div>
49
+ </div>
50
+ </form>
51
+ </body>
52
+ </html>
@@ -0,0 +1,16 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Element by its text</title>
6
+ </head>
7
+ <body>
8
+ <header class="site-header">
9
+ <p>Welcome to the news</p>
10
+ </header>
11
+ <main>
12
+ <p class="news-item">First news item</p>
13
+ <p class="news-item">Second news item</p>
14
+ </main>
15
+ </body>
16
+ </html>
@@ -0,0 +1,27 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Field states</title>
6
+ <style>
7
+ body { font-family: Arial, sans-serif; padding: 20px; }
8
+ label { display: block; margin-top: 12px; }
9
+ </style>
10
+ </head>
11
+ <body>
12
+ <h1>Field states</h1>
13
+ <form id="states-form">
14
+ <label for="state-username">Username</label>
15
+ <input id="state-username" name="username" type="text" value="">
16
+
17
+ <label for="state-account">Account ID</label>
18
+ <input id="state-account" name="account_id" type="text" value="A-100" disabled>
19
+
20
+ <label for="state-reference">Reference</label>
21
+ <input id="state-reference" name="reference" type="text" value="REF-7" readonly>
22
+
23
+ <label for="state-notes">Notes</label>
24
+ <textarea id="state-notes" name="notes" readonly>Kept as written</textarea>
25
+ </form>
26
+ </body>
27
+ </html>
@@ -0,0 +1,26 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Fill in an empty value</title>
6
+ <style>
7
+ body { font-family: Arial, sans-serif; padding: 20px; }
8
+ label { display: block; margin-top: 12px; }
9
+ </style>
10
+ </head>
11
+ <body>
12
+ <h1>Fill in an empty value</h1>
13
+ <p>Every field starts with a value, so a field that is filled with an empty value shows it.</p>
14
+
15
+ <form id="edit-form">
16
+ <label for="title">Title</label>
17
+ <input id="title" name="title" type="text" value="Old title" placeholder="Page title">
18
+
19
+ <label for="summary">Summary</label>
20
+ <textarea id="summary" name="summary" placeholder="Short summary">Old summary</textarea>
21
+
22
+ <label for="keywords">Keywords</label>
23
+ <input id="keywords" class="keywords-field" name="keywords" type="text" value="old, words" placeholder="Comma separated">
24
+ </form>
25
+ </body>
26
+ </html>
@@ -0,0 +1,27 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Fields that cannot be filled</title>
6
+ <style>
7
+ body { font-family: Arial, sans-serif; padding: 20px; }
8
+ label { display: block; margin-top: 12px; }
9
+ </style>
10
+ </head>
11
+ <body>
12
+ <h1>Fields that cannot be filled</h1>
13
+ <form id="locked-form">
14
+ <label for="note">Hidden note</label>
15
+ <textarea id="note" name="note" style="display: none"></textarea>
16
+
17
+ <label for="code">Locked code</label>
18
+ <input id="code" name="code" type="text" value="X1" disabled>
19
+
20
+ <label for="ref">Reference</label>
21
+ <input id="ref" name="reference" type="text" value="R-1" readonly>
22
+
23
+ <label for="visible-name">Your name</label>
24
+ <input id="visible-name" name="visible_name" type="text" placeholder="Full name">
25
+ </form>
26
+ </body>
27
+ </html>
@@ -0,0 +1,29 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>A link repeated in a collapsed menu | Webship-js</title>
6
+ <style>.dropdown { display: none; }</style>
7
+ </head>
8
+ <body>
9
+ <!-- The way a store's top menu repeats every category in a dropdown that is
10
+ hidden until the menu opens: the hidden copy comes first in the page. -->
11
+ <nav aria-label="Main">
12
+ <ul>
13
+ <li>Gear
14
+ <ul class="dropdown">
15
+ <li><a role="menuitem" href="#from-the-menu">Bags</a></li>
16
+ <li><a role="menuitem" href="#from-the-menu">Watches</a></li>
17
+ </ul>
18
+ </li>
19
+ </ul>
20
+ </nav>
21
+ <main>
22
+ <h1>A link repeated in a collapsed menu</h1>
23
+ <aside>
24
+ <h2>Shop by category</h2>
25
+ <a href="#bags">Bags</a>
26
+ </aside>
27
+ </main>
28
+ </body>
29
+ </html>
@@ -0,0 +1,20 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Inner frame</title>
6
+ <style>body { margin: 0; padding: 10px; font-family: Arial, sans-serif; }</style>
7
+ </head>
8
+ <body>
9
+ <p>Text of the inner frame, two levels down</p>
10
+ <p><label for="coupon">Coupon code</label> <input id="coupon" name="coupon_code" type="text" placeholder="Enter a coupon"></p>
11
+ <p><input id="gift" name="gift_note" type="text" placeholder="Gift note"></p>
12
+ <button type="button" aria-label="Apply the coupon" onclick="document.getElementById('status').textContent = 'Coupon ' + document.getElementById('coupon').value + ' applied'">Apply</button>
13
+ <button type="button" title="Remove the coupon" onclick="document.getElementById('status').textContent = 'Coupon removed'">Remove</button>
14
+ <p id="status"></p>
15
+ <p id="late"></p>
16
+ <script>
17
+ setTimeout(function () { document.getElementById('late').textContent = 'A late message from the inner frame'; }, 1500);
18
+ </script>
19
+ </body>
20
+ </html>