webship-js 2.0.1 → 2.0.3

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 (194) hide show
  1. package/AGENTS.md +109 -0
  2. package/CLAUDE.md +317 -0
  3. package/bin/generate-reports.js +363 -0
  4. package/bin/init-webship.js +343 -0
  5. package/bin/postinstall.js +8 -74
  6. package/cucumber.js +66 -2
  7. package/docs/00-quick-start.md +102 -0
  8. package/docs/01-getting-started.md +102 -0
  9. package/docs/02-bbr-smart-waits.md +77 -0
  10. package/docs/03-selector-registry.md +95 -0
  11. package/docs/04-step-reference.md +728 -0
  12. package/docs/05-web-first-assertions.md +91 -0
  13. package/docs/06-network-and-dialogs.md +83 -0
  14. package/docs/07-auth-state.md +75 -0
  15. package/docs/08-clock-mocking.md +59 -0
  16. package/docs/09-api-testing.md +114 -0
  17. package/docs/10-accessibility.md +167 -0
  18. package/docs/11-debugging.md +129 -0
  19. package/docs/12-ai-agent-guide.md +338 -0
  20. package/docs/13-faq.md +236 -0
  21. package/docs/14-recipes-cookbook.md +255 -0
  22. package/docs/15-tag-conventions.md +76 -0
  23. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  24. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  25. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  26. package/docs/advanced-screenshots.md +52 -0
  27. package/docs/advanced-selectors.md +18 -0
  28. package/docs/api-step-definitions.md +45 -0
  29. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  30. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  31. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  32. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  33. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  34. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  35. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  36. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  37. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  38. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  39. package/docs/diffy-step-definitions.md +21 -0
  40. package/docs/global-settings.md +244 -0
  41. package/docs/index.md +104 -0
  42. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  43. package/docs/install-webship-js.md +35 -0
  44. package/docs/overview.md +41 -0
  45. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  46. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  47. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  48. package/docs/step-definitions/then-i-should-be.md +56 -0
  49. package/docs/step-definitions/then-i-should-see.md +62 -0
  50. package/docs/step-definitions/then-item-checkbox.md +54 -0
  51. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  52. package/docs/step-definitions/then-item-should-contain.md +67 -0
  53. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  54. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  55. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  56. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  57. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  58. package/docs/step-definitions/when-i-click-link.md +51 -0
  59. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  60. package/docs/step-definitions/when-i-fill.md +59 -0
  61. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  62. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  63. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  64. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  65. package/docs/step-definitions/when-i-press-button.md +58 -0
  66. package/docs/step-definitions/when-i-reload-page.md +51 -0
  67. package/docs/step-definitions/when-i-scroll.md +73 -0
  68. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  69. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  70. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  71. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  72. package/docs/step-definitions/when-i-wait.md +62 -0
  73. package/docs/step-definitions.md +50 -0
  74. package/examples/a11y.html +31 -0
  75. package/examples/cookies.html +10 -0
  76. package/examples/date.html +12 -0
  77. package/examples/diffy/baseline.html +54 -0
  78. package/examples/diffy/changed.html +63 -0
  79. package/examples/diffy/index.html +52 -0
  80. package/examples/element.html +11 -0
  81. package/examples/field.html +24 -0
  82. package/examples/index.html +6 -0
  83. package/examples/keyboard.html +11 -0
  84. package/examples/links.html +9 -0
  85. package/examples/modal.html +14 -0
  86. package/examples/path.html +3 -0
  87. package/examples/table.html +13 -0
  88. package/examples/test--when--i-additionally-select.html +27 -0
  89. package/package.json +19 -6
  90. package/playwright.config.ts +3 -2
  91. package/tests/features/a11y.feature +39 -0
  92. package/tests/features/cookie.feature +13 -0
  93. package/tests/features/date.feature +11 -0
  94. package/tests/features/diffy/test--diffy-01-example-demo.feature +22 -0
  95. package/tests/features/diffy/test--diffy-02-all-steps.feature +52 -0
  96. package/tests/features/diffy/test--diffy-03-real-api.feature +21 -0
  97. package/tests/features/element.feature +16 -0
  98. package/tests/features/field.feature +25 -0
  99. package/tests/features/keyboard.feature +10 -0
  100. package/tests/features/link.feature +11 -0
  101. package/tests/features/modal-advanced-example.feature +1 -1
  102. package/tests/features/modal.feature +11 -0
  103. package/tests/features/path.feature +16 -0
  104. package/tests/features/response.feature +8 -0
  105. package/tests/features/responsive.feature +10 -0
  106. package/tests/features/table.feature +18 -0
  107. package/tests/features/test--then--i-save-screenshot.feature +33 -0
  108. package/tests/features/test--then--i-see-locator.feature +320 -0
  109. package/tests/features/test--then--i-should-see-n-elements.feature +24 -0
  110. package/tests/features/test--then--print-current-url-and-response.feature +21 -0
  111. package/tests/features/test--when--i-additionally-select.feature +30 -0
  112. package/tests/features/test--when--i-follow.feature +22 -0
  113. package/tests/features/wait.feature +7 -0
  114. package/tests/features/yaml.feature +102 -0
  115. package/tests/reports/README.md +55 -0
  116. package/tests/selectors/_canonical-keys.json +113 -0
  117. package/tests/selectors/back-end-selectors.json +19 -0
  118. package/tests/selectors/cms-contentful-admin.json +35 -0
  119. package/tests/selectors/cms-craft-admin.json +39 -0
  120. package/tests/selectors/cms-drupal-cms-gin.json +56 -0
  121. package/tests/selectors/cms-drupal-core-claro.json +50 -0
  122. package/tests/selectors/cms-generic-admin.json +34 -0
  123. package/tests/selectors/cms-ghost-admin.json +34 -0
  124. package/tests/selectors/cms-joomla-admin.json +41 -0
  125. package/tests/selectors/cms-magento2-admin.json +32 -0
  126. package/tests/selectors/cms-prestashop-admin.json +38 -0
  127. package/tests/selectors/cms-shopify-admin.json +25 -0
  128. package/tests/selectors/cms-strapi-admin.json +42 -0
  129. package/tests/selectors/cms-typo3-admin.json +41 -0
  130. package/tests/selectors/cms-woocommerce-front.json +50 -0
  131. package/tests/selectors/cms-wordpress-admin.json +31 -0
  132. package/tests/selectors/framework-ant-design.json +80 -0
  133. package/tests/selectors/framework-bootstrap.json +86 -0
  134. package/tests/selectors/framework-bulma.json +74 -0
  135. package/tests/selectors/framework-chakra.json +58 -0
  136. package/tests/selectors/framework-foundation.json +51 -0
  137. package/tests/selectors/framework-material-ui.json +72 -0
  138. package/tests/selectors/framework-shadcn.json +51 -0
  139. package/tests/selectors/framework-tailwind.json +40 -0
  140. package/tests/selectors/framework-vuetify.json +61 -0
  141. package/tests/selectors/front-end-selectors.json +16 -0
  142. package/tests/selectors/homepage-selectors.json +13 -0
  143. package/tests/step-definitions/a11y.steps.js +798 -0
  144. package/tests/step-definitions/action.steps.js +167 -0
  145. package/tests/step-definitions/{webship-api.js → api.steps.js} +254 -44
  146. package/tests/step-definitions/assertion.steps.js +352 -0
  147. package/tests/step-definitions/auth.steps.js +124 -0
  148. package/tests/step-definitions/clock.steps.js +128 -0
  149. package/tests/step-definitions/cookie.steps.js +216 -0
  150. package/tests/step-definitions/debug.steps.js +31 -0
  151. package/tests/step-definitions/dialog.steps.js +193 -0
  152. package/tests/step-definitions/element.steps.js +314 -0
  153. package/tests/step-definitions/field.steps.js +653 -0
  154. package/tests/step-definitions/file-download.steps.js +193 -0
  155. package/tests/step-definitions/form.steps.js +333 -0
  156. package/tests/step-definitions/iframe.steps.js +178 -0
  157. package/tests/step-definitions/input.steps.js +163 -0
  158. package/tests/step-definitions/javascript.steps.js +71 -0
  159. package/tests/step-definitions/keyboard.steps.js +78 -0
  160. package/tests/step-definitions/link.steps.js +142 -0
  161. package/tests/step-definitions/metatag.steps.js +91 -0
  162. package/tests/step-definitions/modal.steps.js +219 -0
  163. package/tests/step-definitions/navigation.steps.js +218 -0
  164. package/tests/step-definitions/network.steps.js +238 -0
  165. package/tests/step-definitions/path.steps.js +141 -0
  166. package/tests/step-definitions/response.steps.js +98 -0
  167. package/tests/step-definitions/responsive.steps.js +123 -0
  168. package/tests/step-definitions/rest.steps.js +111 -0
  169. package/tests/step-definitions/screenshot.steps.js +423 -0
  170. package/tests/step-definitions/scroll.steps.js +189 -0
  171. package/tests/step-definitions/selectors.steps.js +996 -0
  172. package/tests/step-definitions/storage.steps.js +194 -0
  173. package/tests/step-definitions/table.steps.js +181 -0
  174. package/tests/step-definitions/wait.steps.js +400 -0
  175. package/tests/step-definitions/web-first.steps.js +296 -0
  176. package/tests/step-definitions/webship.js +567 -923
  177. package/tests/step-definitions/xml.steps.js +409 -0
  178. package/tests/step-definitions/yaml.steps.js +911 -0
  179. package/tests/step-definitions-diffy/README.md +329 -0
  180. package/tests/step-definitions-diffy/mock-diffy-api/server.js +84 -0
  181. package/tests/step-definitions-diffy/webship-diffy-mock.js +31 -0
  182. package/tests/step-definitions-diffy/webship-diffy.js +459 -0
  183. package/tsconfig.json +19 -3
  184. package/generate-reports.js +0 -22
  185. package/required/cucumber.js +0 -37
  186. package/required/generate-reports.js +0 -22
  187. package/required/package.json +0 -18
  188. package/required/playwright.config.ts +0 -37
  189. package/required/tests/features/README.md +0 -1
  190. package/required/tests/features/check-homepage.feature +0 -8
  191. package/required/tests/reports/README.md +0 -1
  192. package/required/tests/step-definitions/README.md +0 -1
  193. package/required/tests/step-definitions/custom.js +0 -4
  194. package/required/tsconfig.json +0 -12
package/AGENTS.md ADDED
@@ -0,0 +1,109 @@
1
+ # AGENTS.md — webship-js
2
+
3
+ This file follows the [agents.md](https://agents.md) convention: short,
4
+ machine-readable rules for any AI agent (Claude, Codex, Cursor, Copilot,
5
+ etc.) working on the repository.
6
+
7
+ For full project context, read `CLAUDE.md` in the same directory — it is
8
+ the canonical, longer policy. This file extracts the critical rules that
9
+ every agent must respect.
10
+
11
+ ## Identity
12
+
13
+ webship-js is a BDD browser-automation harness built on Playwright +
14
+ Cucumber-js. It is its own product. Never reference Behat, DrevOps,
15
+ Drupal, or PHP in code, file names, comments, or step phrasings.
16
+
17
+ ## Hard rules
18
+
19
+ 1. **No git commits.** The user commits manually. Never invoke
20
+ `git commit`, `git push`, `npm publish`, or anything that mutates a
21
+ shared repository / registry without explicit per-action consent.
22
+ 2. **Update docs in the same change.** Step / selector / config changes
23
+ must update the matching page in `docs/`.
24
+ 3. **Stay green.** Every change must keep `npx cucumber-js --dry-run`
25
+ ambiguity-free and `npx cucumber-js` passing.
26
+ 4. **Backups.** When asked, bump `package.json` `version` and emit
27
+ `/var/www/html/products/webship-js-<version>.zip` excluding
28
+ `node_modules/`, `tests/reports/`, `screenshots/`, `.git/`.
29
+
30
+ ## Step definition rules
31
+
32
+ * Use a regex with `(I |we )*` — never `'I ...'` Cucumber Expressions
33
+ unless the step genuinely cannot start with a pronoun.
34
+ * Write step text in plain English. Avoid camelCase identifiers
35
+ (`local storage`, not `localStorage`).
36
+ * Every step needs a JSDoc block with at least 5 `Example #N:` Gherkin
37
+ lines. Each example header line must match the step pattern when the
38
+ Gherkin keyword is stripped.
39
+ * No static `sleep` calls. Wait steps go through `smartSettle()` in
40
+ `webship.js`.
41
+ * Place new steps in the file whose topic matches. Don't create a new
42
+ file unless the topic is genuinely orthogonal to every existing one.
43
+
44
+ ## Do-not-merge boundaries
45
+
46
+ | Pair | Reason |
47
+ | --- | --- |
48
+ | `modal.steps.js` vs `dialog.steps.js` | HTML modal overlay vs native browser alert/confirm/prompt. |
49
+ | `field.steps.js` vs `form.steps.js` | CSS-selector field control vs label/placeholder/name form fills. |
50
+ | `xml.steps.js` vs `yaml.steps.js` | Different parsers and different path conventions. |
51
+ | `api.steps.js` vs `rest.steps.js` | Long-form (header + body table) vs short-form REST steps. |
52
+ | `web-first.steps.js` vs `assertion.steps.js` | Auto-retrying matchers vs single-snapshot assertions. |
53
+ | `element.steps.js` vs `input.steps.js` | Element-scoped (`the element "X"`) vs short pointer (`"X"`). |
54
+
55
+ ## Quick prompt templates
56
+
57
+ **New feature file:** REASONS canvas → comments → Background → Scenarios →
58
+ tags → run.
59
+
60
+ **New step:** search first — if a match exists, point at it instead of
61
+ duplicating. Place by topic. Regex with `(I |we )*`. Plain English. JSDoc
62
+ with ≥5 examples. Friendly try/catch for locator actions.
63
+
64
+ **Maintenance:** run suite → group failures → fix selectors in JSON
65
+ preset (not feature files) → re-run → iterate.
66
+
67
+ **Flaky debug:** `HEADLESS=false SLOW_MO=800` → screenshots/ → replace
68
+ sleeps with edge waits.
69
+
70
+ ## Workflow checklist
71
+
72
+ Before reporting a task complete:
73
+
74
+ * [ ] Ran the affected feature(s) via `LAUNCH_URL=http://localhost:8080 npx cucumber-js <path>`.
75
+ * [ ] Updated `docs/04-step-reference.md` and the topic doc if a step or
76
+ selector preset changed.
77
+ * [ ] Updated `docs/index.md` source layout if a new step file was added.
78
+ * [ ] Verified examples match patterns (no audit mismatches).
79
+ * [ ] Bumped version + produced backup zip if user requested it.
80
+
81
+ ## Wisdom from the Recipes book
82
+
83
+ `docs/12-ai-agent-guide.md` is the AI-specific guide distilled from
84
+ *Webship-js-Recipes v1.0.30*. Read it before authoring features or
85
+ step definitions. Critical takeaways:
86
+
87
+ * **AI generates. Humans validate. Tests verify.**
88
+ * **Test-Drive-Develop:** human writes Gherkin → AI implements → tests
89
+ decide pass / fail.
90
+ * **SPDD REASONS canvas** (Requirements, Entities, Approach, Structure,
91
+ Operations, Norms, Safeguards) — apply it before writing any
92
+ `Scenario:` lines on high-value features.
93
+ * **Fix the prompt first** when reality diverges.
94
+ * **One scenario, one behaviour. Wait for events, not time. Test
95
+ behaviour, not implementation.**
96
+
97
+ ## Source map
98
+
99
+ Step definitions: `tests/step-definitions/`. The `webship.js` file there
100
+ is the single canonical entry point — World, hooks, init script, and
101
+ shared helpers (`smartSettle`, `getModalLocator`, `buildSelector`,
102
+ `gotoUrl`, `fillField`, `getLocatorText`, `pad`, `waitForPageLoad`,
103
+ `waitForModalState`, `findVisibleModal`, `isAnyModalVisible`,
104
+ `getModalSelector`).
105
+
106
+ Docs: `docs/` — see `docs/index.md` for the reading order.
107
+
108
+ Selector presets: `tests/selectors/*.json`. Canonical key list:
109
+ `tests/selectors/_canonical-keys.json`.
package/CLAUDE.md ADDED
@@ -0,0 +1,317 @@
1
+ # CLAUDE.md — webship-js project rules for AI agents
2
+
3
+ This file is the durable contract between human maintainers of webship-js and
4
+ any AI coding assistant working on the repository. Read it in full before
5
+ making changes. Follow it to the letter — these rules emerged from real
6
+ sessions and reflect strong preferences.
7
+
8
+ ## 0. Identity
9
+
10
+ webship-js is a BDD-first browser automation harness built on
11
+ **Playwright + Cucumber-js**. It is its own product. It is **NOT** Behat,
12
+ DrevOps, Drupal, or PHP. Code, file names, comments, and step phrasings
13
+ must never reference those tools or imply that webship-js was ported from
14
+ them. Treat webship-js as the source of truth.
15
+
16
+ ## 1. Communication & change rules
17
+
18
+ 1. **Never commit on the user's behalf.** The user always invokes git
19
+ commits manually. AI work stays uncommitted unless asked.
20
+ 2. **Pause for irreversible operations.** Never `rm -rf`, `git push --force`,
21
+ `npm publish`, or anything that affects shared state without explicit
22
+ confirmation in the same turn.
23
+ 3. **Caveman mode.** When the user has caveman mode active, drop articles,
24
+ filler, and pleasantries in chat replies. Code, commits, security notes,
25
+ and documentation always stay normal English.
26
+ 4. **Update docs with every change.** When you add, rename, remove, or
27
+ restructure a step / selector / configuration option, update the matching
28
+ page under `docs/` in the same turn. Specifically:
29
+ * New / removed step → update `docs/04-step-reference.md`.
30
+ * New step file → add it to the source layout block in `docs/index.md`.
31
+ * Topic-level addition (auth, network, clock, …) → add or refresh the
32
+ dedicated page (`docs/07-auth-state.md`, `docs/06-network-and-dialogs.md`,
33
+ etc.).
34
+ * Selector preset added under `tests/selectors/` → add to the table in
35
+ `docs/03-selector-registry.md`.
36
+ 5. **Backups.** When the user says "backup" or asks for a versioned zip,
37
+ bump the patch version in `package.json` and produce
38
+ `/var/www/html/products/webship-js-<version>.zip`. Excludes:
39
+ `node_modules/`, `tests/reports/`, `screenshots/`, `.git/`.
40
+
41
+ ## 2. Step definition rules
42
+
43
+ ### 2.1 Phrasing
44
+
45
+ * Every step MUST support the pronoun prefix `(I |we )*`. Use a regex
46
+ pattern, not a Cucumber Expression with `'I ...'`, for any step where the
47
+ user could plausibly say "I" or "we".
48
+ * Use plain English in the user-visible step text. Avoid camelCase. Examples:
49
+ * `local storage` — NOT `localStorage`
50
+ * `session storage` — NOT `sessionStorage`
51
+ * Keep technical identifiers (CSS selectors, JSON Pointer paths, header
52
+ names) verbatim — they are domain language, not prose.
53
+ * Never reference Behat, DrevOps, Drupal, PHP, or webship.co versioned
54
+ product names in step phrasings or examples. Use neutral placeholders
55
+ (`example`, `Sample title`, `test-runner`).
56
+
57
+ ### 2.2 JSDoc block — required for every step
58
+
59
+ Every step definition MUST be preceded by a JSDoc block with:
60
+
61
+ * A short description of what the step asserts or does.
62
+ * Implementation notes only when the WHY is non-obvious (e.g. "uses
63
+ Playwright's networkidle plus a custom AJAX counter so late-firing
64
+ setTimeout callbacks re-arm the wait").
65
+ * **At least 5 `Example #N:` lines** of valid Gherkin that match the step
66
+ pattern. Multi-line examples are permitted (continuation lines are
67
+ context — only the example header line needs to match the pattern).
68
+ * Examples MUST use real, plausible data — no escaped JSON inside `"..."`
69
+ strings unless the step accepts a doc string. Avoid quotes-within-quotes
70
+ Gherkin in examples.
71
+
72
+ There is an audit script (`/tmp/audit-examples.js`) used during sessions to
73
+ verify every example matches its step pattern. Keep mismatches at zero.
74
+
75
+ ### 2.3 No duplicate logic
76
+
77
+ Before adding a step, search existing files. Identical Playwright calls
78
+ under different phrasings ARE allowed when the phrasings target different
79
+ audiences (e.g. `I hover over "X"` versus `I hover over the element "X"`).
80
+ True duplicate logic — same code, same conceptual scope — must be merged
81
+ or deleted.
82
+
83
+ ### 2.4 Do NOT merge
84
+
85
+ Some pairs look similar but cover different domains. NEVER merge:
86
+
87
+ | File | Domain |
88
+ | --- | --- |
89
+ | `modal.steps.js` | HTML modal overlays (`role="dialog"`, `.modal`) |
90
+ | `dialog.steps.js` | Native browser dialogs (alert / confirm / prompt) |
91
+ | `field.steps.js` | Input field interactions (CSS selector based) |
92
+ | `form.steps.js` | Form-level fills via label / placeholder / name |
93
+ | `assertion.steps.js` | Page-level text + element assertions |
94
+ | `web-first.steps.js` | Auto-retrying matchers (Playwright web-first style) |
95
+
96
+ ## 3. File organisation
97
+
98
+ ```
99
+ tests/step-definitions/
100
+ ├── webship.js # World, hooks, init script, shared helpers (smartSettle, modal probes, buildSelector, …). Exports → require('./webship') from any *.steps.js.
101
+ ├── navigation.steps.js # Anonymous user, homepage, paths, history, URL/path assertions.
102
+ ├── action.steps.js # press / click / follow / attach file.
103
+ ├── form.steps.js # fill / select / additionally select / check / uncheck / radio.
104
+ ├── assertion.steps.js # see / not see, in row, in element, response, count.
105
+ ├── field.steps.js # field / checkbox / radio / select state assertions.
106
+ ├── modal.steps.js # HTML modal visibility / content / interactions.
107
+ ├── wait.steps.js # ALL wait phrasings (BBR — see §4).
108
+ ├── scroll.steps.js # ALL scroll phrasings (page + scoped element).
109
+ ├── element.steps.js # Element interactions (focus / scroll-to / click-on-the-element / event dispatch / position).
110
+ ├── input.steps.js # Pointer input (hover / drag / dbl-click / right-click / viewport size / tap).
111
+ ├── selectors.steps.js # Named selector registry (CSS + XPath).
112
+ ├── screenshot.steps.js # Screenshot capture + auto-on-failure hook.
113
+ ├── api.steps.js # REST API steps (long form).
114
+ ├── rest.steps.js # REST API steps (short form).
115
+ ├── xml.steps.js # XML response assertions.
116
+ ├── yaml.steps.js # YAML response assertions.
117
+ ├── network.steps.js # Route stubs / blocks / delays / offline.
118
+ ├── dialog.steps.js # Native browser dialog handlers.
119
+ ├── auth.steps.js # storageState save / restore / clear.
120
+ ├── clock.steps.js # page.clock — install / advance / pause / set.
121
+ ├── storage.steps.js # Cookie + local storage + session storage.
122
+ ├── a11y.steps.js # POUR smoke checks (alt, label, landmarks, focus, lang).
123
+ ├── javascript.steps.js # JS error tracking + assertion.
124
+ ├── web-first.steps.js # Auto-retrying state matchers.
125
+ ├── cookie.steps.js # Cookie existence / value assertions.
126
+ ├── keyboard.steps.js # Single key + key combo presses.
127
+ ├── link.steps.js # Link href + title assertions.
128
+ ├── path.steps.js # JSON Pointer path / query parameter assertions.
129
+ ├── response.steps.js # Response header inspection.
130
+ ├── responsive.steps.js # Named breakpoint + explicit viewport sizing.
131
+ ├── table.steps.js # Data-table assertions.
132
+ ├── metatag.steps.js # <meta> tag assertions.
133
+ ├── iframe.steps.js # Frame switching + frame-scoped interactions.
134
+ ├── file-download.steps.js # Download capture + assertions.
135
+ └── debug.steps.js # print URL / last response.
136
+ ```
137
+
138
+ When you add a new step, place it in the file whose topic matches. Do NOT
139
+ spawn a new file unless the topic is genuinely orthogonal to every
140
+ existing file. New file → mention it in `docs/index.md` AND update the
141
+ table above.
142
+
143
+ ## 4. Behavior-Based Robotics (BBR) wait policy
144
+
145
+ Static `sleep` is forbidden in step bodies. Every wait step uses
146
+ `smartSettle(page, budget)` from `webship.js`, which composites:
147
+
148
+ 1. `<body>` attached
149
+ 2. `DOMContentLoaded` fired
150
+ 3. Playwright `networkidle`
151
+ 4. `window.__webshipAjaxCount === 0` (custom fetch / XHR counter)
152
+ 5. `window.__webshipPendingTimers === 0` (custom `setTimeout` counter)
153
+ 6. `Date.now() - window.__webshipLastMutation >= 250 ms` (DOM-quiet)
154
+
155
+ The init script that installs counters 4 / 5 / 6 lives in `webship.js`'s
156
+ `openBrowser()` via `context.addInitScript()`. Never strip it.
157
+
158
+ Auto-settle hook: `AfterStep` runs `smartSettle(page, 1500)` after every
159
+ step whose text matches `STATE_MUTATING_STEP` (click / press / fill / …).
160
+ This is what makes `When I click "X" Then I should see "Y"` work without
161
+ an explicit wait. Disable per-run with `WEBSHIP_AUTO_SETTLE=off`.
162
+
163
+ ## 5. Selector registry
164
+
165
+ * Selectors live in `tests/selectors/*.json`, two top-level keys: `css`,
166
+ `xpath`.
167
+ * Built-in presets are normalised against `_canonical-keys.json`. New
168
+ presets MUST use canonical key names where possible — `notice success`
169
+ not `alert-success`, `main nav` not `admin menu`, `data table` not
170
+ `entries table`.
171
+ * Named selector resolution priority: `css` registry first, then `xpath`
172
+ (auto-prefixed with `xpath=`). Register in three ways: inline (`When I
173
+ add "X" selector for "Y" css selector`), bulk via data table, or JSON
174
+ files listed in `worldParameters.selectors.files`.
175
+ * Custom modal selector: every preset SHOULD expose a `modal` key. The
176
+ modal helpers in `webship.js` use it before falling back to
177
+ `[role="dialog"], dialog`.
178
+
179
+ ## 6. Run modes
180
+
181
+ | Script | Effect |
182
+ | --- | --- |
183
+ | `npm test` | Default — pretty output, slow-mo 300 ms. |
184
+ | `npm run test:headed` | Headed browser, `SLOW_MO=800`. |
185
+ | `npm run test:fast` | `SLOW_MO=0`, single-process, full feature set. |
186
+ | `BROWSER={chromium\|firefox\|webkit} npm test` | Pick browser. |
187
+
188
+ For parallel + retry pass CLI flags directly:
189
+ `npx cucumber-js --parallel 4 --retry 1 --retry-tag-filter @flaky`.
190
+
191
+ Env vars: `LAUNCH_URL`, `BROWSER`, `HEADLESS`, `SLOW_MO`,
192
+ `WEBSHIP_AUTO_SETTLE`, `WEBSHIP_REPORT_DISABLE`, `WEBSHIP_REPORT_ARGS`,
193
+ `WEBSHIP_SCREENSHOT_*`.
194
+
195
+ ## 7. Tests must stay green
196
+
197
+ Before declaring a task done:
198
+
199
+ 1. Run `npx cucumber-js --dry-run` — no ambiguity, no undefined steps.
200
+ 2. Run the full suite via `LAUNCH_URL=http://localhost:8080 npx cucumber-js`.
201
+ All scenarios must pass.
202
+ 3. If there are mismatches between examples and step patterns, fix them.
203
+ Use the audit pattern: walk every JSDoc Example, strip the Gherkin
204
+ keyword, and confirm the remainder matches the step regex.
205
+
206
+ ## 8. AI agent wisdom — see [docs/12-ai-agent-guide.md](docs/12-ai-agent-guide.md)
207
+
208
+ That page distils the canonical guidance from *Webship-js-Recipes v1.0.30*
209
+ into one reference. Internalise these:
210
+
211
+ * **AI generates. Humans validate. Tests verify.** AI does not know what
212
+ "correct" means for the business. The test suite is the executable
213
+ contract.
214
+ * **Test-Drive-Develop loop.** Human writes feature file → human
215
+ prompts AI → AI implements → tests verify. Pass = ship. Fail =
216
+ iterate.
217
+ * **SPDD REASONS canvas.** Every prompt covers Requirements, Entities,
218
+ Approach, Structure, Operations, Norms, Safeguards. Webship-js
219
+ feature files map cleanly to it.
220
+ * **Cardinal SPDD rule.** When reality diverges from the prompt,
221
+ **fix the prompt first**, then update the code.
222
+ * **Three Amigos before scenarios.** Product / QA / Dev questions get
223
+ answered in `Feature:` description before any `Scenario:` lines.
224
+ * **DAMP / KISS / YAGNI / MMF.** Self-contained scenarios, simplest
225
+ test that fails, no speculative features, smallest piece of value.
226
+ * **Golden rules** — see §AI Agent Guide for the full ten. Top three:
227
+ test behaviour not implementation, wait for events not time, one
228
+ behaviour per scenario.
229
+ * **AI pitfalls.** Over-trusting output, implementation tests, missing
230
+ edge cases, false confidence. Mitigation: AI generates, humans
231
+ validate against business requirements.
232
+
233
+ ## 9. AI prompts — concrete templates
234
+
235
+ When asked to do common tasks, use these templates. They are battle-tested.
236
+
237
+ ### Generate a feature file from a user story
238
+
239
+ ```
240
+ Read templates/spdd-feature.md (REASONS canvas).
241
+ Fill every section before writing any Gherkin.
242
+ Place the filled-in canvas as # comments at the top of tests/features/<name>.feature.
243
+ Generate one Scenario per Operations item.
244
+ Tag each scenario with the relevant Norm / Safeguard category
245
+ (@critical, @auth, @a11y, @security, @i18n).
246
+ Use built-in steps. Only write a custom step when no preset matches —
247
+ and place it in the file whose topic matches (see CLAUDE.md §3).
248
+ Run npx cucumber-js tests/features/<name>.feature when done.
249
+ ```
250
+
251
+ ### Add a custom step
252
+
253
+ ```
254
+ Search tests/step-definitions/*.steps.js for an existing matching step.
255
+ If one exists, point me at it instead of duplicating.
256
+ Pick the file whose topic matches.
257
+ Use a regex with (I |we )* — never plain 'I ...' Cucumber Expressions.
258
+ Plain English only — no camelCase identifiers in step text.
259
+ Add a JSDoc block with at least 5 Example #N: Gherkin lines.
260
+ Wrap risky locator actions with a friendly try/catch that explains
261
+ the failure (see action.steps.js actOrExplain helper).
262
+ Run npx cucumber-js --dry-run to confirm no ambiguity.
263
+ Run the affected feature(s) to confirm green.
264
+ ```
265
+
266
+ ### Maintain tests after a UI change
267
+
268
+ ```
269
+ Run the suite. Capture every failure: scenario name + step + expected/actual.
270
+ Group failures by root cause (usually 2-3 causes drive 90% of red).
271
+ For text-only changes, find/replace the step text in feature files.
272
+ For structural changes, update the named selector in tests/selectors/<preset>.json.
273
+ Re-run. Iterate until green. Commit prompt + code + selector changes together.
274
+ ```
275
+
276
+ ### Debug a flaky test
277
+
278
+ ```
279
+ Re-run with HEADLESS=false SLOW_MO=800 to watch what really happens.
280
+ Look at screenshots/failed_*.png for the moment of failure.
281
+ Replace any wait Ns with an edge wait:
282
+ wait until the URL contains "..."
283
+ wait for "selector" to appear
284
+ web-first matcher with within N seconds.
285
+ Verify each scenario creates its own data — no cross-scenario state.
286
+ If the bug is timing only in CI, bump the budget on the smart wait,
287
+ do NOT add static sleeps.
288
+ ```
289
+
290
+ ### Run the project locally
291
+
292
+ ```
293
+ npm install
294
+ npm start # dev server on localhost:8080 (or set LAUNCH_URL)
295
+ npm test # full suite
296
+ npx cucumber-js --dry-run # confirm no ambiguity, no undefined
297
+ ```
298
+
299
+ ### Rules of engagement (for the prompt itself)
300
+
301
+ When the user gives an ambiguous task, ASK before guessing. Specifically:
302
+
303
+ - "Where should this step live?" — pick the file whose topic matches §3.
304
+ - "Should this be a custom step or compose existing ones?" — prefer
305
+ composing existing steps inside a feature scenario.
306
+ - "Should I commit?" — never. The user always commits manually.
307
+ - "Should I update docs?" — yes, in the same change. See §1.4.
308
+ - "Should I bump the version + zip?" — only when the user says "backup".
309
+
310
+ ## 10. Avoid
311
+
312
+ * Comments that describe WHAT the code does — names already do that.
313
+ * Backwards-compatibility shims for unused code paths — delete unused code.
314
+ * Renaming `_unused` for variables — delete them.
315
+ * Adding feature flags for hypothetical future requirements.
316
+ * `// removed` comments — git history is the record, not the file.
317
+ * Replacing existing selectors with synonyms when canonical keys exist.