webship-js 2.0.11 → 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.
Files changed (168) hide show
  1. package/.circleci/config.yml +10 -1
  2. package/.drone.yml +7 -7
  3. package/.github/workflows/github-actions.yml +45 -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 +44 -8
  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/choice-controls.html +29 -0
  45. package/examples/datetime-fields.html +52 -0
  46. package/examples/element-selector-hint.html +16 -0
  47. package/examples/field-states.html +27 -0
  48. package/examples/fill-in-empty.html +26 -0
  49. package/examples/fill-unreachable.html +27 -0
  50. package/examples/iframe-inner.html +20 -0
  51. package/examples/iframe-nested.html +16 -0
  52. package/examples/iframe-outer.html +15 -0
  53. package/examples/multi-value-fields.html +54 -0
  54. package/examples/registered-names.html +15 -0
  55. package/examples/select-by-label.html +33 -0
  56. package/examples/settle-budget.html +21 -0
  57. package/examples/sorted-tables.html +38 -0
  58. package/examples/text-matching.html +48 -0
  59. package/examples/text-order.html +25 -0
  60. package/examples/touch.html +22 -0
  61. package/examples/viewport-top.html +36 -0
  62. package/package.json +16 -1
  63. package/playwright.config.ts +3 -1
  64. package/tests/check-api-launch-url.js +106 -0
  65. package/tests/check-assets.js +103 -0
  66. package/tests/check-attachments.js +105 -0
  67. package/tests/check-breakpoints.js +117 -0
  68. package/tests/check-clock.js +143 -0
  69. package/tests/check-config.js +90 -0
  70. package/tests/check-context.js +215 -0
  71. package/tests/check-dry-run.js +104 -0
  72. package/tests/check-examples.js +10 -4
  73. package/tests/check-exit-report.js +141 -0
  74. package/tests/check-javascript-errors.js +105 -0
  75. package/tests/check-must-fail.js +5 -4
  76. package/tests/check-scaffold.js +36 -1
  77. package/tests/check-screenshots.js +117 -0
  78. package/tests/check-settle-verbs.js +137 -0
  79. package/tests/check-time-limit.js +104 -0
  80. package/tests/check-video.js +156 -0
  81. package/tests/check-world.js +167 -0
  82. package/tests/features/api-base-url.feature +25 -0
  83. package/tests/features/api-form-data.feature +18 -0
  84. package/tests/features/api-json-paths.feature +24 -0
  85. package/tests/features/api-response-contains.feature +21 -0
  86. package/tests/features/api-response-header-presence.feature +17 -0
  87. package/tests/features/api-response-header.feature +17 -0
  88. package/tests/features/api-saved-placeholders.feature +37 -0
  89. package/tests/features/api-step-definitions-individual.feature +1 -1
  90. package/tests/features/api-tables.feature +40 -0
  91. package/tests/features/breakpoints.feature +25 -0
  92. package/tests/features/choice-controls.feature +35 -0
  93. package/tests/features/complete-api-testing-examples.feature +1 -1
  94. package/tests/features/datetime-field-lookup.feature +29 -0
  95. package/tests/features/element-selector-hint.feature +14 -0
  96. package/tests/features/field-state.feature +21 -0
  97. package/tests/features/fill-in-empty-value.feature +41 -0
  98. package/tests/features/fill-reachable.feature +13 -0
  99. package/tests/features/iframe-nested.feature +43 -0
  100. package/tests/features/javascript-tolerated-errors.feature +20 -0
  101. package/tests/features/modal-open.feature +13 -0
  102. package/tests/features/multi-value-field-lookup.feature +30 -0
  103. package/tests/features/registered-names.feature +14 -0
  104. package/tests/features/select-by-label.feature +31 -0
  105. package/tests/features/selector-files.feature +14 -0
  106. package/tests/features/selectors-table-header.feature +35 -0
  107. package/tests/features/settle-budget.feature +11 -0
  108. package/tests/features/sorted-tables.feature +19 -0
  109. package/tests/features/storage-quoted-values.feature +26 -0
  110. package/tests/features/text-matching.feature +38 -0
  111. package/tests/features/text-order.feature +14 -0
  112. package/tests/features/touch.feature +21 -0
  113. package/tests/features/viewport-top.feature +13 -0
  114. package/tests/features/xml-namespaces.feature +34 -0
  115. package/tests/must-fail/api-json-paths.feature +21 -0
  116. package/tests/must-fail/api-response-contains.feature +23 -0
  117. package/tests/must-fail/api-response-header-presence.feature +17 -0
  118. package/tests/must-fail/api-response-header.feature +21 -0
  119. package/tests/must-fail/api-without-base-url.feature +11 -0
  120. package/tests/must-fail/breakpoints.feature +15 -0
  121. package/tests/must-fail/choice-controls.feature +25 -0
  122. package/tests/must-fail/clock.feature +11 -0
  123. package/tests/must-fail/datetime-field.feature +10 -0
  124. package/tests/must-fail/element-selector-hint.feature +17 -0
  125. package/tests/must-fail/field-state.feature +20 -0
  126. package/tests/must-fail/fill-field.feature +30 -0
  127. package/tests/must-fail/iframe-text.feature +17 -0
  128. package/tests/must-fail/modal-open.feature +26 -0
  129. package/tests/must-fail/multi-value-field.feature +18 -0
  130. package/tests/must-fail/registered-names.feature +25 -0
  131. package/tests/must-fail/select-list.feature +15 -0
  132. package/tests/must-fail/selector-files.feature +10 -0
  133. package/tests/must-fail/sorted-tables.feature +20 -0
  134. package/tests/must-fail/storage-before-a-page.feature +13 -0
  135. package/tests/must-fail/text-matching.feature +16 -0
  136. package/tests/must-fail/text-order.feature +15 -0
  137. package/tests/must-fail/viewport-top.feature +20 -0
  138. package/tests/must-fail/yaml-numbers.feature +48 -0
  139. package/tests/step-definitions/a11y.steps.js +24 -15
  140. package/tests/step-definitions/action.steps.js +22 -8
  141. package/tests/step-definitions/api.steps.js +349 -67
  142. package/tests/step-definitions/assertion.steps.js +100 -10
  143. package/tests/step-definitions/auth.steps.js +15 -18
  144. package/tests/step-definitions/clock.steps.js +22 -0
  145. package/tests/step-definitions/debug.steps.js +8 -0
  146. package/tests/step-definitions/dialog.steps.js +7 -0
  147. package/tests/step-definitions/element.steps.js +132 -17
  148. package/tests/step-definitions/field.steps.js +409 -96
  149. package/tests/step-definitions/form.steps.js +76 -29
  150. package/tests/step-definitions/iframe.steps.js +89 -29
  151. package/tests/step-definitions/input.steps.js +26 -7
  152. package/tests/step-definitions/javascript.steps.js +64 -22
  153. package/tests/step-definitions/modal.steps.js +79 -13
  154. package/tests/step-definitions/navigation.steps.js +14 -0
  155. package/tests/step-definitions/network.steps.js +15 -5
  156. package/tests/step-definitions/response.steps.js +6 -4
  157. package/tests/step-definitions/responsive.steps.js +26 -33
  158. package/tests/step-definitions/screenshot.steps.js +25 -8
  159. package/tests/step-definitions/scroll.steps.js +20 -0
  160. package/tests/step-definitions/selectors.steps.js +95 -48
  161. package/tests/step-definitions/storage.steps.js +38 -13
  162. package/tests/step-definitions/table.steps.js +81 -6
  163. package/tests/step-definitions/video.steps.js +52 -55
  164. package/tests/step-definitions/wait.steps.js +88 -23
  165. package/tests/step-definitions/web-first.steps.js +69 -35
  166. package/tests/step-definitions/webship.js +681 -143
  167. package/tests/step-definitions/xml.steps.js +49 -15
  168. package/tests/step-definitions/yaml.steps.js +45 -20
@@ -11,6 +11,8 @@ Then "#dashboard" should be visible
11
11
  Then "#dashboard" should be visible within 12 seconds
12
12
  ```
13
13
 
14
+ A `within N seconds` longer than the step timeout (45 seconds, `WEBSHIP_STEP_TIMEOUT`) is kept: the step waits the N seconds it was given, as `I wait 2 minutes` and `eventually I should see "…" within 90 seconds` do, and fails with its own message, not with "function timed out". Such a step bounds itself at its length plus 15 seconds, so a page that stopped answering cannot hang the run.
15
+
14
16
  ## State matchers
15
17
 
16
18
  ```gherkin
@@ -37,6 +39,8 @@ Then "<sel>" should be in the viewport
37
39
  Then "<sel>" should not be in the viewport within 3 seconds
38
40
  ```
39
41
 
42
+ `the element "<sel>" should be at the top of the viewport` passes when the top of the element is between 0 and 100 pixels from the top of the viewport. It looks again for up to 5 seconds, so an element still on its way after a smooth scroll gets there, and its failure gives the measured top.
43
+
40
44
  ## Count
41
45
 
42
46
  ```gherkin
@@ -54,6 +58,8 @@ Then "<sel>" should have value "alice@example.com"
54
58
 
55
59
  `should have text` is the exact match: the element's text, trimmed. `should contain text` collapses every run of whitespace to one space, on the element's text and on the expected text, before it looks for the substring, so a line the markup wraps still matches.
56
60
 
61
+ For a text anywhere on the page, `I should see "text"` and `I should not see "text"` wait up to 5 seconds and `eventually I should see "text" within N seconds` longer. They ignore letter case and count the text of hidden elements, unlike `should have text` and `should contain text`, which match the letter case of the one element they read. See [Then I should see](step-definitions/then-i-should-see.md).
62
+
57
63
  ## Attributes / classes
58
64
 
59
65
  ```gherkin
@@ -41,7 +41,7 @@ Feature: Admin dashboard
41
41
  And "<#user-list>" should have a count of 5 within 5 seconds
42
42
  ```
43
43
 
44
- `I restore the auth state from "..."` swaps the current browser context for a fresh one with the saved cookies/localStorage. The tracker init script is reinstalled automatically so smart waits keep working.
44
+ `I restore the auth state from "..."` swaps the current browser context for a fresh one with the saved cookies/localStorage, opened the same way as the first one of the scenario: the smart-wait init script, the viewport of an `@mobile` / `@desktop` tag, video recording while it is on, JavaScript-error capture, the response tracker and a running request log all go on with the new page. The new page starts blank, so open the page you need next. Routes stubbed before the step (`the URL "…" returns …`) belonged to the closed context: stub them after it.
45
45
 
46
46
  ## Clearing auth
47
47
 
@@ -45,13 +45,32 @@ Scenario: "5 minutes ago" updates as time passes
45
45
 
46
46
  ```gherkin
47
47
  Scenario: Idle warning fires at 14 minutes
48
- Given the system time is "2026-05-08T10:00:00Z"
49
- And I restore the auth state from "tests/auth/admin.json"
48
+ Given I restore the auth state from "tests/auth/admin.json"
49
+ And the system time is "2026-05-08T10:00:00Z"
50
50
  And I am on "/dashboard"
51
51
  When I advance the clock by 14 minutes
52
52
  Then "<#session-warning>" should be visible
53
53
  ```
54
54
 
55
+ Restore the auth state first: restoring it opens a new browser context, and the clock belongs to the context it replaced. The same goes for starting or stopping a video recording.
56
+
57
+ ## Smart waits under a fake clock
58
+
59
+ The smart waits keep real time: the settle after a step does not count the
60
+ clock's timers (they belong to the clock, not to the page's work) and
61
+ measures the DOM-quiet window on the real clock, so a navigation or a press
62
+ settles as soon as the page is quiet, not after its whole budget.
63
+
64
+ `When I wait until pending timers settle` cannot see the timers of a page
65
+ under a fake clock — they run only when the clock moves — so it fails at
66
+ once and asks you to advance the clock instead.
67
+
68
+ The clock steps move the clock that `Given the system time is "…"`
69
+ installed. Without it, Playwright installs one on the first clock step, at
70
+ the current time: the timers the page set before that step keep running on
71
+ real time and do not move with the clock. Webship-js prints a note (and
72
+ attaches it to the report) when that happens.
73
+
55
74
  ## Caveats
56
75
 
57
76
  - `requestAnimationFrame` and `MutationObserver` are not on the fake clock. Animations driven by `rAF` keep playing in real time.
@@ -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&role=admin
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 captured from earlier responses or scenario data:
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`:
@@ -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
@@ -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
@@ -212,6 +212,11 @@ When asked to add a custom step:
212
212
  6. Run the audit: `npm run test:examples`. It fails when a definition has
213
213
  no JSDoc description or no example, when a step line of an example
214
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`.
215
220
 
216
221
  ### Recipe AI-3: Maintain tests after a UI change
217
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
 
@@ -136,6 +188,10 @@ Then I should see "Welcome, Alice" # ✅ user behaviour
136
188
  Behaviour-tested code is refactor-friendly. Implementation-tested code
137
189
  breaks every time the schema changes.
138
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
+
139
195
  ## How do I name selectors I'll reuse?
140
196
 
141
197
  In `tests/selectors/my-app.json`:
@@ -218,6 +274,21 @@ Layered approach in [10 Accessibility](10-accessibility.md). Combine
218
274
  custom probes (heading order, skip link, ARIA validity) with axe-core
219
275
  full audits.
220
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
+
221
292
  ## How do I make CI fast?
222
293
 
223
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: the scenario opens at the `desktop` breakpoint (1200 × 900) or the `mobile` breakpoint (375 × 667), or at the sizes `worldParameters.selectors.breakpoints` gives those two names. `@mobile` wins when both are set. A step can still change the viewport. A mobile lane: `--tags "@mobile"`. |
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