webship-js 2.0.2 → 2.0.4

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 (181) hide show
  1. package/.circleci/config.yml +7 -31
  2. package/.drone.yml +68 -0
  3. package/.harness/webship-js-pipeline.yml +101 -0
  4. package/.semaphore/semaphore.yml +58 -0
  5. package/.teamcity/pom.xml +52 -0
  6. package/.teamcity/settings.kts +92 -0
  7. package/.travis.yml +24 -3
  8. package/AGENTS.md +109 -0
  9. package/CLAUDE.md +317 -0
  10. package/Jenkinsfile +54 -0
  11. package/azure-pipelines.yml +82 -0
  12. package/bamboo-specs/bamboo.yml +131 -0
  13. package/bin/generate-reports.js +181 -9
  14. package/buildspec.yml +56 -0
  15. package/cloudbuild.yaml +49 -0
  16. package/codefresh.yml +77 -0
  17. package/cucumber.js +48 -5
  18. package/docs/00-quick-start.md +102 -0
  19. package/docs/01-getting-started.md +102 -0
  20. package/docs/02-bbr-smart-waits.md +77 -0
  21. package/docs/03-selector-registry.md +95 -0
  22. package/docs/04-step-reference.md +799 -0
  23. package/docs/05-web-first-assertions.md +91 -0
  24. package/docs/06-network-and-dialogs.md +83 -0
  25. package/docs/07-auth-state.md +75 -0
  26. package/docs/08-clock-mocking.md +59 -0
  27. package/docs/09-api-testing.md +114 -0
  28. package/docs/10-accessibility.md +167 -0
  29. package/docs/11-debugging.md +129 -0
  30. package/docs/12-ai-agent-guide.md +338 -0
  31. package/docs/13-faq.md +236 -0
  32. package/docs/14-recipes-cookbook.md +255 -0
  33. package/docs/15-tag-conventions.md +76 -0
  34. package/docs/16-ci-cd.md +879 -0
  35. package/docs/README.md +113 -0
  36. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
  37. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
  38. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
  39. package/docs/advanced-screenshots.md +52 -0
  40. package/docs/advanced-selectors.md +18 -0
  41. package/docs/api-step-definitions.md +45 -0
  42. package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
  43. package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
  44. package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
  45. package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
  46. package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
  47. package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
  48. package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
  49. package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
  50. package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
  51. package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
  52. package/docs/diffy-step-definitions.md +21 -0
  53. package/docs/global-settings.md +295 -0
  54. package/docs/install-webship-js/ddev-webship-js.md +52 -0
  55. package/docs/install-webship-js.md +35 -0
  56. package/docs/overview.md +41 -0
  57. package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
  58. package/docs/step-definitions/given-i-am-homepage.md +68 -0
  59. package/docs/step-definitions/given-i-am-specific-page.md +72 -0
  60. package/docs/step-definitions/then-i-should-be.md +56 -0
  61. package/docs/step-definitions/then-i-should-see.md +62 -0
  62. package/docs/step-definitions/then-item-checkbox.md +54 -0
  63. package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
  64. package/docs/step-definitions/then-item-should-contain.md +67 -0
  65. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
  66. package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
  67. package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
  68. package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
  69. package/docs/step-definitions/when-i-check-checkbox.md +60 -0
  70. package/docs/step-definitions/when-i-click-link.md +51 -0
  71. package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
  72. package/docs/step-definitions/when-i-fill.md +59 -0
  73. package/docs/step-definitions/when-i-go-homepage.md +60 -0
  74. package/docs/step-definitions/when-i-go-specific-page.md +67 -0
  75. package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
  76. package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
  77. package/docs/step-definitions/when-i-press-button.md +58 -0
  78. package/docs/step-definitions/when-i-reload-page.md +51 -0
  79. package/docs/step-definitions/when-i-scroll.md +73 -0
  80. package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
  81. package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
  82. package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
  83. package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
  84. package/docs/step-definitions/when-i-wait.md +62 -0
  85. package/docs/step-definitions.md +50 -0
  86. package/examples/a11y.html +31 -0
  87. package/examples/cookies.html +10 -0
  88. package/examples/date.html +12 -0
  89. package/examples/element.html +11 -0
  90. package/examples/field.html +24 -0
  91. package/examples/keyboard.html +11 -0
  92. package/examples/links.html +9 -0
  93. package/examples/modal.html +14 -0
  94. package/examples/path.html +3 -0
  95. package/examples/table.html +13 -0
  96. package/examples/video-demo.html +43 -0
  97. package/package.json +10 -3
  98. package/playwright.config.ts +3 -2
  99. package/tests/features/a11y.feature +39 -0
  100. package/tests/features/cookie.feature +13 -0
  101. package/tests/features/date.feature +11 -0
  102. package/tests/features/element.feature +16 -0
  103. package/tests/features/field.feature +25 -0
  104. package/tests/features/keyboard.feature +10 -0
  105. package/tests/features/link.feature +11 -0
  106. package/tests/features/modal-advanced-example.feature +1 -1
  107. package/tests/features/modal.feature +11 -0
  108. package/tests/features/path.feature +16 -0
  109. package/tests/features/response.feature +8 -0
  110. package/tests/features/responsive.feature +10 -0
  111. package/tests/features/table.feature +18 -0
  112. package/tests/features/video.feature +18 -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 +7 -1
  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/step-definitions/a11y.steps.js +800 -0
  142. package/tests/step-definitions/action.steps.js +167 -0
  143. package/tests/step-definitions/{webship-api.js → api.steps.js} +41 -23
  144. package/tests/step-definitions/assertion.steps.js +352 -0
  145. package/tests/step-definitions/auth.steps.js +126 -0
  146. package/tests/step-definitions/clock.steps.js +128 -0
  147. package/tests/step-definitions/cookie.steps.js +216 -0
  148. package/tests/step-definitions/debug.steps.js +39 -0
  149. package/tests/step-definitions/dialog.steps.js +193 -0
  150. package/tests/step-definitions/element.steps.js +356 -0
  151. package/tests/step-definitions/field.steps.js +653 -0
  152. package/tests/step-definitions/file-download.steps.js +211 -0
  153. package/tests/step-definitions/form.steps.js +333 -0
  154. package/tests/step-definitions/iframe.steps.js +228 -0
  155. package/tests/step-definitions/input.steps.js +202 -0
  156. package/tests/step-definitions/javascript.steps.js +232 -0
  157. package/tests/step-definitions/keyboard.steps.js +112 -0
  158. package/tests/step-definitions/link.steps.js +142 -0
  159. package/tests/step-definitions/metatag.steps.js +91 -0
  160. package/tests/step-definitions/modal.steps.js +244 -0
  161. package/tests/step-definitions/navigation.steps.js +218 -0
  162. package/tests/step-definitions/network.steps.js +280 -0
  163. package/tests/step-definitions/path.steps.js +141 -0
  164. package/tests/step-definitions/response.steps.js +98 -0
  165. package/tests/step-definitions/responsive.steps.js +125 -0
  166. package/tests/step-definitions/rest.steps.js +111 -0
  167. package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
  168. package/tests/step-definitions/scroll.steps.js +189 -0
  169. package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +64 -27
  170. package/tests/step-definitions/storage.steps.js +194 -0
  171. package/tests/step-definitions/table.steps.js +181 -0
  172. package/tests/step-definitions/video.steps.js +178 -0
  173. package/tests/step-definitions/wait.steps.js +400 -0
  174. package/tests/step-definitions/web-first.steps.js +298 -0
  175. package/tests/step-definitions/webship.js +741 -1477
  176. package/tests/step-definitions/xml.steps.js +411 -0
  177. package/tests/step-definitions/yaml.steps.js +913 -0
  178. package/tests/step-definitions-diffy/webship-diffy.js +0 -13
  179. package/tsconfig.json +19 -3
  180. package/videos/README.md +32 -0
  181. package/.travis-ci.yml +0 -16
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/README.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/README.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.
package/Jenkinsfile ADDED
@@ -0,0 +1,54 @@
1
+ // Jenkins declarative pipeline for webship-js.
2
+ //
3
+ // Runs the full BDD suite against an http-server fixture on port 8080.
4
+ // Uses the official Playwright image so chromium + all apt deps are baked in.
5
+ //
6
+ // Requirements on the Jenkins controller:
7
+ // - Docker Pipeline plugin (built into the "suggested plugins" install)
8
+ // - One executor with the docker daemon reachable
9
+ //
10
+ // Drop the file at repo root and configure a Pipeline job that points
11
+ // "Pipeline script from SCM" at this branch.
12
+
13
+ pipeline {
14
+ agent {
15
+ docker {
16
+ image 'mcr.microsoft.com/playwright:v1.58.2-jammy'
17
+ args '-u root:root'
18
+ }
19
+ }
20
+ options {
21
+ timestamps()
22
+ ansiColor('xterm')
23
+ timeout(time: 30, unit: 'MINUTES')
24
+ buildDiscarder(logRotator(numToKeepStr: '20'))
25
+ }
26
+ environment {
27
+ FORCE_COLOR = '1'
28
+ LAUNCH_URL = 'http://localhost:8080'
29
+ }
30
+ stages {
31
+ stage('Install') {
32
+ steps { sh 'npm install' }
33
+ }
34
+ stage('Browsers') {
35
+ steps { sh 'npx playwright install --with-deps chromium' }
36
+ }
37
+ stage('Serve fixtures') {
38
+ steps {
39
+ sh 'nohup npm start > /tmp/srv.log 2>&1 &'
40
+ sh 'sleep 3'
41
+ sh 'curl -sf http://localhost:8080/ > /dev/null'
42
+ }
43
+ }
44
+ stage('Test') {
45
+ steps { sh 'npm test' }
46
+ }
47
+ }
48
+ post {
49
+ always {
50
+ archiveArtifacts artifacts: 'tests/reports/cucumber_report.html,tests/reports/cucumber_report.pdf,tests/reports/cucumber_report.json,screenshots/**/*',
51
+ allowEmptyArchive: true
52
+ }
53
+ }
54
+ }
@@ -0,0 +1,82 @@
1
+ # Azure DevOps Pipelines for webship-js.
2
+ #
3
+ # Runs the full BDD suite on a Microsoft-hosted Ubuntu agent. Free tier for
4
+ # public projects: 10 parallel jobs, unlimited minutes. Free tier for private
5
+ # projects: 1 job, 1,800 minutes / month.
6
+ #
7
+ # Setup:
8
+ # 1. dev.azure.com → sign in → create Organization → create Project.
9
+ # 2. Pipelines → New pipeline → GitHub → authorise OAuth.
10
+ # 3. "Existing Azure Pipelines YAML file" → /azure-pipelines.yml.
11
+ #
12
+ # Badge after first run (paste in README.md):
13
+ # ![Azure Pipelines](https://dev.azure.com/<org>/<project>/_apis/build/status/webship-js?branchName=2.0.x)
14
+
15
+ trigger:
16
+ branches:
17
+ include:
18
+ - 2.0.x
19
+ tags:
20
+ include:
21
+ - '2.0.*'
22
+
23
+ pr:
24
+ branches:
25
+ include:
26
+ - 2.0.x
27
+
28
+ pool:
29
+ vmImage: 'ubuntu-latest'
30
+
31
+ variables:
32
+ FORCE_COLOR: '1'
33
+ LAUNCH_URL: 'http://localhost:8080'
34
+
35
+ steps:
36
+ - task: NodeTool@0
37
+ inputs:
38
+ versionSpec: '20.x'
39
+ displayName: 'Install Node 20'
40
+
41
+ - task: Cache@2
42
+ inputs:
43
+ key: '"npm" | "$(Agent.OS)" | package.json'
44
+ restoreKeys: '"npm" | "$(Agent.OS)"'
45
+ path: $(Pipeline.Workspace)/.npm
46
+ displayName: 'Cache npm'
47
+
48
+ - task: Cache@2
49
+ inputs:
50
+ key: '"playwright" | "$(Agent.OS)"'
51
+ restoreKeys: '"playwright" | "$(Agent.OS)"'
52
+ path: $(HOME)/.cache/ms-playwright
53
+ displayName: 'Cache Playwright browsers'
54
+
55
+ - script: npm install
56
+ displayName: 'Install npm dependencies'
57
+
58
+ - script: npx playwright install --with-deps chromium
59
+ displayName: 'Install Playwright browsers'
60
+
61
+ - script: |
62
+ nohup npm start > /tmp/srv.log 2>&1 &
63
+ sleep 3
64
+ curl -sf http://localhost:8080/ > /dev/null
65
+ displayName: 'Start virtual server'
66
+
67
+ - script: npm test
68
+ displayName: 'Run tests'
69
+
70
+ - task: PublishBuildArtifacts@1
71
+ condition: always()
72
+ inputs:
73
+ pathToPublish: 'tests/reports'
74
+ artifactName: 'cucumber-report'
75
+ displayName: 'Publish HTML / PDF / JSON report'
76
+
77
+ - task: PublishBuildArtifacts@1
78
+ condition: failed()
79
+ inputs:
80
+ pathToPublish: 'screenshots'
81
+ artifactName: 'failure-screenshots'
82
+ displayName: 'Publish failure screenshots'
@@ -0,0 +1,131 @@
1
+ # Atlassian Bamboo YAML Specs for webship-js.
2
+ #
3
+ # Runs the full BDD suite on a Bamboo Data Center self-hosted instance.
4
+ # (Bamboo Cloud was retired by Atlassian on 2024-02-15; the YAML below
5
+ # targets Bamboo Data Center 9.x — which is the only flavour still
6
+ # supported.)
7
+ #
8
+ # Setup (full walkthrough in docs/16-ci-cd.md → "Bamboo Data Center"):
9
+ # 1. Bamboo admin → Linked repositories → add the GitHub repo.
10
+ # 2. Bamboo admin → Specs → Repositories → enable specs scanning on
11
+ # that repo so this file is read on every push.
12
+ #
13
+ # References:
14
+ # - https://confluence.atlassian.com/bamboo/bamboo-yaml-specs-1054778761.html
15
+
16
+ ---
17
+ version: 2
18
+
19
+ plan:
20
+ project-key: WEB # 3+ uppercase chars (project key)
21
+ key: JS # plan key — final id WEB-JS
22
+ name: webship-js
23
+ description: Webship-js BDD test suite (Playwright + Cucumber-js)
24
+
25
+ stages:
26
+ - Test:
27
+ jobs:
28
+ - Cucumber
29
+
30
+ Cucumber:
31
+ key: CUC
32
+ docker:
33
+ image: mcr.microsoft.com/playwright:v1.58.2-jammy
34
+ docker-run-arguments:
35
+ - --user=root:root
36
+ - --network=host
37
+ tasks:
38
+ - checkout:
39
+ force-clean-build: true
40
+ - script:
41
+ description: Show toolchain versions
42
+ scripts:
43
+ - node --version
44
+ - npm --version
45
+ - script:
46
+ description: Install npm dependencies
47
+ scripts:
48
+ - npm install
49
+ - script:
50
+ description: Install Playwright browsers
51
+ scripts:
52
+ - npx playwright install --with-deps chromium
53
+ - script:
54
+ description: Start fixture server
55
+ scripts:
56
+ - nohup npm start > /tmp/srv.log 2>&1 &
57
+ - sleep 3
58
+ - curl -sf http://localhost:8080/ > /dev/null
59
+ - script:
60
+ description: Run cucumber suite
61
+ scripts:
62
+ - npm test
63
+ artifacts:
64
+ - name: cucumber-report-html
65
+ pattern: tests/reports/cucumber_report.html
66
+ shared: true
67
+ required: false
68
+ - name: cucumber-report-pdf
69
+ pattern: tests/reports/cucumber_report.pdf
70
+ shared: true
71
+ required: false
72
+ - name: cucumber-report-json
73
+ pattern: tests/reports/cucumber_report.json
74
+ shared: true
75
+ required: false
76
+ - name: screenshots
77
+ pattern: screenshots/**
78
+ shared: true
79
+ required: false
80
+ requirements:
81
+ - os: Linux
82
+
83
+ triggers:
84
+ - polling:
85
+ period: 60 # poll every 60s
86
+ condition:
87
+ any-branch: '^2\.0\.x$'
88
+
89
+ branches:
90
+ create: manually
91
+ delete: never
92
+
93
+ variables:
94
+ FORCE_COLOR: "1"
95
+ LAUNCH_URL: "http://localhost:8080"
96
+
97
+ repositories:
98
+ - webship-js:
99
+ scope: global # already linked at admin level
100
+
101
+ notifications: []
102
+
103
+ labels:
104
+ - webship-js
105
+ - bdd
106
+ - playwright
107
+ - cucumber-js
108
+
109
+ other:
110
+ concurrent-build-plugin: system-default
111
+
112
+ ---
113
+ version: 2
114
+ plan-permissions:
115
+ project-key: WEB
116
+ plan-key: JS
117
+ permissions:
118
+ - users:
119
+ - admin
120
+ permissions:
121
+ - view
122
+ - edit
123
+ - build
124
+ - admin
125
+ - groups:
126
+ - bamboo-admin
127
+ permissions:
128
+ - admin
129
+ - view
130
+ - build
131
+ - edit