webship-js 2.0.2 → 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.
- package/AGENTS.md +109 -0
- package/CLAUDE.md +317 -0
- package/bin/generate-reports.js +181 -9
- package/cucumber.js +10 -4
- package/docs/00-quick-start.md +102 -0
- package/docs/01-getting-started.md +102 -0
- package/docs/02-bbr-smart-waits.md +77 -0
- package/docs/03-selector-registry.md +95 -0
- package/docs/04-step-reference.md +728 -0
- package/docs/05-web-first-assertions.md +91 -0
- package/docs/06-network-and-dialogs.md +83 -0
- package/docs/07-auth-state.md +75 -0
- package/docs/08-clock-mocking.md +59 -0
- package/docs/09-api-testing.md +114 -0
- package/docs/10-accessibility.md +167 -0
- package/docs/11-debugging.md +129 -0
- package/docs/12-ai-agent-guide.md +338 -0
- package/docs/13-faq.md +236 -0
- package/docs/14-recipes-cookbook.md +255 -0
- package/docs/15-tag-conventions.md +76 -0
- package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +36 -0
- package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +34 -0
- package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +45 -0
- package/docs/advanced-screenshots.md +52 -0
- package/docs/advanced-selectors.md +18 -0
- package/docs/api-step-definitions.md +45 -0
- package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +30 -0
- package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +21 -0
- package/docs/diffy-step-definitions/then-create-diffy-comparison.md +25 -0
- package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +35 -0
- package/docs/diffy-step-definitions/then-i-take-screenshot.md +21 -0
- package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +27 -0
- package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +27 -0
- package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +28 -0
- package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +21 -0
- package/docs/diffy-step-definitions/when-i-resize-window-number.md +29 -0
- package/docs/diffy-step-definitions.md +21 -0
- package/docs/global-settings.md +244 -0
- package/docs/index.md +104 -0
- package/docs/install-webship-js/ddev-webship-js.md +52 -0
- package/docs/install-webship-js.md +35 -0
- package/docs/overview.md +41 -0
- package/docs/step-definitions/given-i-am-anonymous-user.md +67 -0
- package/docs/step-definitions/given-i-am-homepage.md +68 -0
- package/docs/step-definitions/given-i-am-specific-page.md +72 -0
- package/docs/step-definitions/then-i-should-be.md +56 -0
- package/docs/step-definitions/then-i-should-see.md +62 -0
- package/docs/step-definitions/then-item-checkbox.md +54 -0
- package/docs/step-definitions/then-item-link-should-contain-url.md +84 -0
- package/docs/step-definitions/then-item-should-contain.md +67 -0
- package/docs/step-definitions/then-radio-button-value-should-be-selected.md +68 -0
- package/docs/step-definitions/then-response-status-code-should-be-number.md +69 -0
- package/docs/step-definitions/then-value-radio-button-selected.md +62 -0
- package/docs/step-definitions/when-i-attach-file-file-name-element.md +71 -0
- package/docs/step-definitions/when-i-check-checkbox.md +60 -0
- package/docs/step-definitions/when-i-click-link.md +51 -0
- package/docs/step-definitions/when-i-click-operation-text-row.md +71 -0
- package/docs/step-definitions/when-i-fill.md +59 -0
- package/docs/step-definitions/when-i-go-homepage.md +60 -0
- package/docs/step-definitions/when-i-go-specific-page.md +67 -0
- package/docs/step-definitions/when-i-move-backward-one-page.md +49 -0
- package/docs/step-definitions/when-i-move-forward-one-page.md +58 -0
- package/docs/step-definitions/when-i-press-button.md +58 -0
- package/docs/step-definitions/when-i-reload-page.md +51 -0
- package/docs/step-definitions/when-i-scroll.md +73 -0
- package/docs/step-definitions/when-i-select-option-select-list.md +53 -0
- package/docs/step-definitions/when-i-select-radio-button-value.md +62 -0
- package/docs/step-definitions/when-i-uncheck-checkbox.md +57 -0
- package/docs/step-definitions/when-i-wait-ajax-finish.md +64 -0
- package/docs/step-definitions/when-i-wait.md +62 -0
- package/docs/step-definitions.md +50 -0
- package/examples/a11y.html +31 -0
- package/examples/cookies.html +10 -0
- package/examples/date.html +12 -0
- package/examples/element.html +11 -0
- package/examples/field.html +24 -0
- package/examples/keyboard.html +11 -0
- package/examples/links.html +9 -0
- package/examples/modal.html +14 -0
- package/examples/path.html +3 -0
- package/examples/table.html +13 -0
- package/package.json +10 -3
- package/playwright.config.ts +3 -2
- package/tests/features/a11y.feature +39 -0
- package/tests/features/cookie.feature +13 -0
- package/tests/features/date.feature +11 -0
- package/tests/features/element.feature +16 -0
- package/tests/features/field.feature +25 -0
- package/tests/features/keyboard.feature +10 -0
- package/tests/features/link.feature +11 -0
- package/tests/features/modal-advanced-example.feature +1 -1
- package/tests/features/modal.feature +11 -0
- package/tests/features/path.feature +16 -0
- package/tests/features/response.feature +8 -0
- package/tests/features/responsive.feature +10 -0
- package/tests/features/table.feature +18 -0
- package/tests/features/wait.feature +7 -0
- package/tests/features/yaml.feature +102 -0
- package/tests/reports/README.md +55 -0
- package/tests/selectors/_canonical-keys.json +113 -0
- package/tests/selectors/back-end-selectors.json +7 -1
- package/tests/selectors/cms-contentful-admin.json +35 -0
- package/tests/selectors/cms-craft-admin.json +39 -0
- package/tests/selectors/cms-drupal-cms-gin.json +56 -0
- package/tests/selectors/cms-drupal-core-claro.json +50 -0
- package/tests/selectors/cms-generic-admin.json +34 -0
- package/tests/selectors/cms-ghost-admin.json +34 -0
- package/tests/selectors/cms-joomla-admin.json +41 -0
- package/tests/selectors/cms-magento2-admin.json +32 -0
- package/tests/selectors/cms-prestashop-admin.json +38 -0
- package/tests/selectors/cms-shopify-admin.json +25 -0
- package/tests/selectors/cms-strapi-admin.json +42 -0
- package/tests/selectors/cms-typo3-admin.json +41 -0
- package/tests/selectors/cms-woocommerce-front.json +50 -0
- package/tests/selectors/cms-wordpress-admin.json +31 -0
- package/tests/selectors/framework-ant-design.json +80 -0
- package/tests/selectors/framework-bootstrap.json +86 -0
- package/tests/selectors/framework-bulma.json +74 -0
- package/tests/selectors/framework-chakra.json +58 -0
- package/tests/selectors/framework-foundation.json +51 -0
- package/tests/selectors/framework-material-ui.json +72 -0
- package/tests/selectors/framework-shadcn.json +51 -0
- package/tests/selectors/framework-tailwind.json +40 -0
- package/tests/selectors/framework-vuetify.json +61 -0
- package/tests/step-definitions/a11y.steps.js +798 -0
- package/tests/step-definitions/action.steps.js +167 -0
- package/tests/step-definitions/{webship-api.js → api.steps.js} +24 -7
- package/tests/step-definitions/assertion.steps.js +352 -0
- package/tests/step-definitions/auth.steps.js +124 -0
- package/tests/step-definitions/clock.steps.js +128 -0
- package/tests/step-definitions/cookie.steps.js +216 -0
- package/tests/step-definitions/debug.steps.js +31 -0
- package/tests/step-definitions/dialog.steps.js +193 -0
- package/tests/step-definitions/element.steps.js +314 -0
- package/tests/step-definitions/field.steps.js +653 -0
- package/tests/step-definitions/file-download.steps.js +193 -0
- package/tests/step-definitions/form.steps.js +333 -0
- package/tests/step-definitions/iframe.steps.js +178 -0
- package/tests/step-definitions/input.steps.js +163 -0
- package/tests/step-definitions/javascript.steps.js +71 -0
- package/tests/step-definitions/keyboard.steps.js +78 -0
- package/tests/step-definitions/link.steps.js +142 -0
- package/tests/step-definitions/metatag.steps.js +91 -0
- package/tests/step-definitions/modal.steps.js +219 -0
- package/tests/step-definitions/navigation.steps.js +218 -0
- package/tests/step-definitions/network.steps.js +238 -0
- package/tests/step-definitions/path.steps.js +141 -0
- package/tests/step-definitions/response.steps.js +98 -0
- package/tests/step-definitions/responsive.steps.js +123 -0
- package/tests/step-definitions/rest.steps.js +111 -0
- package/tests/step-definitions/{webship-screenshot.js → screenshot.steps.js} +1 -5
- package/tests/step-definitions/scroll.steps.js +189 -0
- package/tests/step-definitions/{webship-selectors.js → selectors.steps.js} +46 -11
- package/tests/step-definitions/storage.steps.js +194 -0
- package/tests/step-definitions/table.steps.js +181 -0
- package/tests/step-definitions/wait.steps.js +400 -0
- package/tests/step-definitions/web-first.steps.js +296 -0
- package/tests/step-definitions/webship.js +552 -1507
- package/tests/step-definitions/xml.steps.js +409 -0
- package/tests/step-definitions/yaml.steps.js +911 -0
- package/tests/step-definitions-diffy/webship-diffy.js +0 -13
- package/tsconfig.json +19 -3
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.
|