webship-js 2.0.4 → 2.0.5
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/.drone.yml +0 -0
- package/.harness/webship-js-pipeline.yml +0 -0
- package/.semaphore/semaphore.yml +0 -0
- package/.teamcity/pom.xml +0 -0
- package/.teamcity/settings.kts +0 -0
- package/.travis.yml +0 -0
- package/AGENTS.md +50 -14
- package/CLAUDE.md +326 -104
- package/Jenkinsfile +0 -0
- package/azure-pipelines.yml +0 -0
- package/bamboo-specs/bamboo.yml +0 -0
- package/bin/init-webship.js +0 -13
- package/bin/postinstall.js +0 -0
- package/buildspec.yml +0 -0
- package/cloudbuild.yaml +0 -0
- package/codefresh.yml +0 -0
- package/cucumber.js +0 -12
- package/docs/00-quick-start.md +0 -0
- package/docs/01-getting-started.md +0 -0
- package/docs/02-bbr-smart-waits.md +0 -0
- package/docs/03-selector-registry.md +0 -0
- package/docs/04-step-reference.md +0 -0
- package/docs/05-web-first-assertions.md +0 -0
- package/docs/06-network-and-dialogs.md +0 -0
- package/docs/07-auth-state.md +0 -0
- package/docs/08-clock-mocking.md +0 -0
- package/docs/09-api-testing.md +0 -0
- package/docs/10-accessibility.md +0 -0
- package/docs/11-debugging.md +0 -0
- package/docs/12-ai-agent-guide.md +0 -0
- package/docs/13-faq.md +0 -0
- package/docs/14-recipes-cookbook.md +0 -0
- package/docs/15-tag-conventions.md +0 -0
- package/docs/16-ci-cd.md +0 -0
- package/docs/README.md +4 -1
- package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +0 -0
- package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +0 -0
- package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +0 -0
- package/docs/advanced-screenshots.md +0 -0
- package/docs/advanced-selectors.md +0 -0
- package/docs/api-step-definitions.md +0 -0
- package/docs/global-settings.md +0 -28
- package/docs/install-webship-js/ddev-webship-js.md +0 -0
- package/docs/install-webship-js.md +0 -1
- package/docs/overview.md +0 -1
- package/docs/step-definitions/given-i-am-anonymous-user.md +0 -0
- package/docs/step-definitions/given-i-am-homepage.md +0 -0
- package/docs/step-definitions/given-i-am-specific-page.md +0 -0
- package/docs/step-definitions/then-i-should-be.md +0 -0
- package/docs/step-definitions/then-i-should-see.md +0 -0
- package/docs/step-definitions/then-item-checkbox.md +0 -0
- package/docs/step-definitions/then-item-link-should-contain-url.md +0 -0
- package/docs/step-definitions/then-item-should-contain.md +0 -0
- package/docs/step-definitions/then-radio-button-value-should-be-selected.md +0 -0
- package/docs/step-definitions/then-response-status-code-should-be-number.md +0 -0
- package/docs/step-definitions/then-value-radio-button-selected.md +0 -0
- package/docs/step-definitions/when-i-attach-file-file-name-element.md +0 -0
- package/docs/step-definitions/when-i-check-checkbox.md +0 -0
- package/docs/step-definitions/when-i-click-link.md +0 -0
- package/docs/step-definitions/when-i-click-operation-text-row.md +0 -0
- package/docs/step-definitions/when-i-fill.md +0 -0
- package/docs/step-definitions/when-i-go-homepage.md +0 -0
- package/docs/step-definitions/when-i-go-specific-page.md +0 -0
- package/docs/step-definitions/when-i-move-backward-one-page.md +0 -0
- package/docs/step-definitions/when-i-move-forward-one-page.md +0 -0
- package/docs/step-definitions/when-i-press-button.md +0 -0
- package/docs/step-definitions/when-i-reload-page.md +0 -0
- package/docs/step-definitions/when-i-scroll.md +0 -0
- package/docs/step-definitions/when-i-select-option-select-list.md +0 -0
- package/docs/step-definitions/when-i-select-radio-button-value.md +0 -0
- package/docs/step-definitions/when-i-uncheck-checkbox.md +0 -0
- package/docs/step-definitions/when-i-wait-ajax-finish.md +0 -0
- package/docs/step-definitions/when-i-wait.md +0 -0
- package/docs/step-definitions.md +0 -0
- package/examples/a11y.html +0 -0
- package/examples/account.html +0 -0
- package/examples/ajax-wait-examples.html +0 -0
- package/examples/cookies.html +0 -0
- package/examples/date.html +0 -0
- package/examples/dynamic-examples.html +0 -0
- package/examples/element.html +0 -0
- package/examples/field.html +0 -0
- package/examples/keyboard.html +0 -0
- package/examples/links.html +0 -0
- package/examples/modal.html +0 -0
- package/examples/path.html +0 -0
- package/examples/table.html +0 -0
- package/examples/test--modal-dialogs.html +0 -0
- package/examples/test--when--i-additionally-select.html +0 -0
- package/examples/test--when--i-select-radio-button.html +0 -0
- package/examples/video-demo.html +0 -0
- package/package.json +1 -1
- package/playwright.config.ts +0 -0
- package/tests/assets/test-document.pdf +0 -0
- package/tests/features/a11y.feature +0 -0
- package/tests/features/ajax-wait-examples.feature +0 -0
- package/tests/features/cookie.feature +0 -0
- package/tests/features/date.feature +0 -0
- package/tests/features/dynamic-content-examples.feature +0 -0
- package/tests/features/element.feature +0 -0
- package/tests/features/field.feature +0 -0
- package/tests/features/keyboard.feature +0 -0
- package/tests/features/link.feature +0 -0
- package/tests/features/modal-advanced-example.feature +0 -0
- package/tests/features/modal-basic-example.feature +0 -0
- package/tests/features/modal-error-handling-example.feature +0 -0
- package/tests/features/modal.feature +0 -0
- package/tests/features/path.feature +0 -0
- package/tests/features/response.feature +0 -0
- package/tests/features/responsive.feature +0 -0
- package/tests/features/table.feature +0 -0
- package/tests/features/test--given--i-am-an-anonymous-user.feature +0 -0
- package/tests/features/test--then--i-save-screenshot.feature +0 -0
- package/tests/features/test--then--i-see-locator.feature +0 -0
- package/tests/features/test--then--i-should-see-n-elements.feature +0 -0
- package/tests/features/test--then--print-current-url-and-response.feature +0 -0
- package/tests/features/test--when--i-additionally-select.feature +0 -0
- package/tests/features/test--when--i-follow.feature +0 -0
- package/tests/features/test--when--i-select-radio-button.feature +0 -0
- package/tests/features/video.feature +0 -0
- package/tests/features/wait.feature +0 -0
- package/tests/features/yaml.feature +0 -0
- package/tests/reports/README.md +0 -0
- package/tests/selectors/_canonical-keys.json +0 -0
- package/tests/selectors/back-end-selectors.json +0 -0
- package/tests/selectors/cms-contentful-admin.json +0 -0
- package/tests/selectors/cms-craft-admin.json +0 -0
- package/tests/selectors/cms-drupal-cms-gin.json +0 -0
- package/tests/selectors/cms-drupal-core-claro.json +0 -0
- package/tests/selectors/cms-generic-admin.json +0 -0
- package/tests/selectors/cms-ghost-admin.json +0 -0
- package/tests/selectors/cms-joomla-admin.json +0 -0
- package/tests/selectors/cms-magento2-admin.json +0 -0
- package/tests/selectors/cms-prestashop-admin.json +0 -0
- package/tests/selectors/cms-shopify-admin.json +0 -0
- package/tests/selectors/cms-strapi-admin.json +0 -0
- package/tests/selectors/cms-typo3-admin.json +0 -0
- package/tests/selectors/cms-woocommerce-front.json +0 -0
- package/tests/selectors/cms-wordpress-admin.json +0 -0
- package/tests/selectors/framework-ant-design.json +0 -0
- package/tests/selectors/framework-bootstrap.json +0 -0
- package/tests/selectors/framework-bulma.json +0 -0
- package/tests/selectors/framework-chakra.json +0 -0
- package/tests/selectors/framework-foundation.json +0 -0
- package/tests/selectors/framework-material-ui.json +0 -0
- package/tests/selectors/framework-shadcn.json +0 -0
- package/tests/selectors/framework-tailwind.json +0 -0
- package/tests/selectors/framework-vuetify.json +0 -0
- package/tests/selectors/front-end-selectors.json +0 -0
- package/tests/selectors/homepage-selectors.json +0 -0
- package/tests/step-definitions/a11y.steps.js +0 -0
- package/tests/step-definitions/action.steps.js +0 -0
- package/tests/step-definitions/assertion.steps.js +0 -0
- package/tests/step-definitions/auth.steps.js +0 -0
- package/tests/step-definitions/clock.steps.js +0 -0
- package/tests/step-definitions/cookie.steps.js +0 -0
- package/tests/step-definitions/debug.steps.js +0 -0
- package/tests/step-definitions/dialog.steps.js +0 -0
- package/tests/step-definitions/element.steps.js +0 -0
- package/tests/step-definitions/field.steps.js +0 -0
- package/tests/step-definitions/file-download.steps.js +0 -0
- package/tests/step-definitions/form.steps.js +0 -0
- package/tests/step-definitions/iframe.steps.js +0 -0
- package/tests/step-definitions/input.steps.js +0 -0
- package/tests/step-definitions/javascript.steps.js +0 -0
- package/tests/step-definitions/keyboard.steps.js +0 -0
- package/tests/step-definitions/link.steps.js +0 -0
- package/tests/step-definitions/metatag.steps.js +0 -0
- package/tests/step-definitions/modal.steps.js +0 -0
- package/tests/step-definitions/navigation.steps.js +0 -0
- package/tests/step-definitions/network.steps.js +0 -0
- package/tests/step-definitions/path.steps.js +0 -0
- package/tests/step-definitions/response.steps.js +0 -0
- package/tests/step-definitions/responsive.steps.js +0 -0
- package/tests/step-definitions/rest.steps.js +0 -0
- package/tests/step-definitions/screenshot.steps.js +0 -0
- package/tests/step-definitions/scroll.steps.js +0 -0
- package/tests/step-definitions/selectors.steps.js +0 -0
- package/tests/step-definitions/storage.steps.js +0 -0
- package/tests/step-definitions/table.steps.js +0 -0
- package/tests/step-definitions/video.steps.js +0 -0
- package/tests/step-definitions/wait.steps.js +0 -0
- package/tests/step-definitions/web-first.steps.js +0 -0
- package/tests/step-definitions/xml.steps.js +0 -0
- package/tests/step-definitions/yaml.steps.js +0 -0
- package/tsconfig.json +0 -0
- package/videos/README.md +0 -0
- package/docs/diffy-step-definitions/then-compare-diffy-env1-env2.md +0 -30
- package/docs/diffy-step-definitions/then-create-diffy-comparison-name-value.md +0 -21
- package/docs/diffy-step-definitions/then-create-diffy-comparison.md +0 -25
- package/docs/diffy-step-definitions/then-create-diffy-screenshot-environment-name.md +0 -35
- package/docs/diffy-step-definitions/then-i-take-screenshot.md +0 -21
- package/docs/diffy-step-definitions/then-i-take-screenshots-all-breakpoints.md +0 -27
- package/docs/diffy-step-definitions/then-send-screenshots-diffy-name-value.md +0 -27
- package/docs/diffy-step-definitions/then-upload-folder-url-diffy-snapshotname.md +0 -28
- package/docs/diffy-step-definitions/then-wait-diffy-comparison-complete.md +0 -21
- package/docs/diffy-step-definitions/when-i-resize-window-number.md +0 -29
- package/docs/diffy-step-definitions.md +0 -21
- package/examples/diffy/baseline.html +0 -54
- package/examples/diffy/changed.html +0 -63
- package/examples/diffy/index.html +0 -52
- package/tests/features/diffy/test--diffy-01-example-demo.feature +0 -22
- package/tests/features/diffy/test--diffy-02-all-steps.feature +0 -52
- package/tests/features/diffy/test--diffy-03-real-api.feature +0 -21
- package/tests/step-definitions-diffy/README.md +0 -329
- package/tests/step-definitions-diffy/mock-diffy-api/server.js +0 -84
- package/tests/step-definitions-diffy/webship-diffy-mock.js +0 -31
- package/tests/step-definitions-diffy/webship-diffy.js +0 -459
package/CLAUDE.md
CHANGED
|
@@ -1,9 +1,12 @@
|
|
|
1
|
-
# CLAUDE.md
|
|
1
|
+
# CLAUDE.md
|
|
2
2
|
|
|
3
|
-
This file
|
|
3
|
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
4
|
+
|
|
5
|
+
It is also the durable contract between human maintainers of webship-js and
|
|
4
6
|
any AI coding assistant working on the repository. Read it in full before
|
|
5
7
|
making changes. Follow it to the letter — these rules emerged from real
|
|
6
|
-
sessions and reflect strong preferences.
|
|
8
|
+
sessions and reflect strong preferences. `AGENTS.md` is the short,
|
|
9
|
+
machine-readable extract of the same rules; keep the two in sync.
|
|
7
10
|
|
|
8
11
|
## 0. Identity
|
|
9
12
|
|
|
@@ -13,7 +16,160 @@ DrevOps, Drupal, or PHP. Code, file names, comments, and step phrasings
|
|
|
13
16
|
must never reference those tools or imply that webship-js was ported from
|
|
14
17
|
them. Treat webship-js as the source of truth.
|
|
15
18
|
|
|
16
|
-
|
|
19
|
+
Current line: **2.0.x** (branch `2.0.x`; `1.0.x` is the older main branch).
|
|
20
|
+
Node **≥ 20**.
|
|
21
|
+
|
|
22
|
+
## 1. Commands
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npm install # required first — node_modules is not committed
|
|
26
|
+
npx playwright install --with-deps chromium # browser binaries (CI does this too)
|
|
27
|
+
npm start # http-server over examples/ on :8080 (the fixture site)
|
|
28
|
+
npm test # full suite, pretty output, slowMo 300ms
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
`npm start` must be running (or `LAUNCH_URL` pointed elsewhere) before the
|
|
32
|
+
suite — nearly every bundled feature loads a static fixture from `examples/`.
|
|
33
|
+
|
|
34
|
+
| Command | Effect |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
| `npm test` | Default — pretty output, slow-mo 300 ms, headless chromium. |
|
|
37
|
+
| `npm run test:headed` | `HEADLESS=false`, slow-mo auto-bumps to 800 ms. |
|
|
38
|
+
| `npm run test:fast` | `SLOW_MO=0`. |
|
|
39
|
+
| `npm run test:chromium` / `:firefox` / `:webkit` | Pick the browser (same as `BROWSER=…`). |
|
|
40
|
+
| `npx cucumber-js --dry-run` | Ambiguity / undefined-step check. Run this before declaring done. |
|
|
41
|
+
| `npm run generate-reports` | HTML (+ optional PDF) report from `tests/reports/cucumber_report.json`. |
|
|
42
|
+
|
|
43
|
+
Targeting a subset:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx cucumber-js tests/features/modal.feature # one feature file
|
|
47
|
+
npx cucumber-js tests/features/modal.feature:12 # one scenario, by line
|
|
48
|
+
npx cucumber-js --name "Dashboard renders" # by scenario name
|
|
49
|
+
npx cucumber-js --tags "@critical and not @wip" # by tag
|
|
50
|
+
npx cucumber-js --parallel 4 --retry 1 --retry-tag-filter @flaky
|
|
51
|
+
LAUNCH_URL=http://localhost:8080 npx cucumber-js # point at another target
|
|
52
|
+
HEADLESS=false SLOW_MO=800 npx cucumber-js tests/features/x.feature # watch a flake
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Env vars: `LAUNCH_URL`, `BROWSER`, `HEADLESS`, `SLOW_MO`, `FORCE_COLOR`,
|
|
56
|
+
`WEBSHIP_AUTO_SETTLE`, `WEBSHIP_REPORT_DISABLE`, `WEBSHIP_REPORT_ARGS`,
|
|
57
|
+
`WEBSHIP_FILTER_HOOK_LINES`, `WEBSHIP_SCREENSHOT_*`, `WEBSHIP_VIDEO*`,
|
|
58
|
+
`WEBSHIP_JS_ERROR_*`, `WEBSHIP_SELECTORS_OFFSET`,
|
|
59
|
+
`WEBSHIP_SELECTORS_BREAKPOINTS`, `DIFFY_*`. Every one of them mirrors a
|
|
60
|
+
`worldParameters` key in `cucumber.js` — that file is the annotated
|
|
61
|
+
reference; read it before inventing a new knob.
|
|
62
|
+
|
|
63
|
+
## 2. Architecture
|
|
64
|
+
|
|
65
|
+
### 2.1 This repo is a library **and** its own test suite
|
|
66
|
+
|
|
67
|
+
`tests/` serves double duty: it is the step-definition library shipped to
|
|
68
|
+
consumers on npm *and* the self-test suite proving those steps work
|
|
69
|
+
against the static fixtures in `examples/`. A change to a step must keep
|
|
70
|
+
both roles green.
|
|
71
|
+
|
|
72
|
+
Consumer projects install the package and get scaffolded by
|
|
73
|
+
`bin/postinstall.js` → `bin/init-webship.js`, which writes a `cucumber.js`
|
|
74
|
+
whose `require` array points at
|
|
75
|
+
`node_modules/webship-js/tests/step-definitions/**/*.js` plus the
|
|
76
|
+
project's own `tests/step-definitions/`. Postinstall is a no-op when a
|
|
77
|
+
`cucumber.js` already exists, so re-installs never clobber user config.
|
|
78
|
+
**If you change the shape of `cucumber.js` `worldParameters`, update the
|
|
79
|
+
`CUCUMBER_JS` template inside `bin/init-webship.js` in the same change** —
|
|
80
|
+
otherwise new projects get scaffolded with a stale config.
|
|
81
|
+
|
|
82
|
+
### 2.2 `tests/step-definitions/webship.js` — the single canonical entry point
|
|
83
|
+
|
|
84
|
+
Everything shared lives here; every `*.steps.js` does
|
|
85
|
+
`require('./webship')`. It owns, in one file:
|
|
86
|
+
|
|
87
|
+
* **The World** (`PlaywrightWorld extends World`) — `page`, `context`,
|
|
88
|
+
`playwrightBrowser`, `frame` (iframe scope), `launchUrl`, `minWaitTime`,
|
|
89
|
+
`assetsFolder`, and the named-selector registries `__selectorsCss` /
|
|
90
|
+
`__selectorsXpath`. `setDefaultTimeout(45s)` — deliberately above
|
|
91
|
+
Playwright's 30 s default so locator timeouts reach our try/catch
|
|
92
|
+
wrappers and testers see a friendly message, not "function timed out".
|
|
93
|
+
The 45 s in `cucumber.js` exists for the same reason; keep them aligned.
|
|
94
|
+
* **The init script** installed via `context.addInitScript()` in
|
|
95
|
+
`openBrowser()` — monkey-patches `fetch`, `XMLHttpRequest.send`,
|
|
96
|
+
`setTimeout`/`clearTimeout` and attaches a `MutationObserver` to
|
|
97
|
+
maintain `window.__webshipAjaxCount`, `__webshipPendingTimers`,
|
|
98
|
+
`__webshipLastMutation`. This is the substrate the whole wait policy
|
|
99
|
+
stands on. **Never strip it.**
|
|
100
|
+
* **Hooks** — `Before({order:5})` opens the browser (merging
|
|
101
|
+
`recordVideo` context options when video is on); `After({order:5})`
|
|
102
|
+
captures the video path *before* closing the context, saves/deletes per
|
|
103
|
+
mode, then closes the browser; `BeforeStep` resolves `[relative:…]` date
|
|
104
|
+
tokens in step text, doc strings, and data-table cells; `AfterStep`
|
|
105
|
+
runs the auto-settle.
|
|
106
|
+
* **Shared helpers** (exported): `smartSettle`, `waitForPageLoad`,
|
|
107
|
+
`buildSelector`, `gotoUrl`, `fillField`, `getLocatorText`, `pad`,
|
|
108
|
+
the modal probes (`getModalSelector`, `getModalLocator`,
|
|
109
|
+
`waitForModalState`, `findVisibleModal`, `isAnyModalVisible`), the date
|
|
110
|
+
helpers (`resolveRelativeDate`, `parseRelativeOffset`,
|
|
111
|
+
`formatRelativeDate`), and the error builders (`friendly`, `humanize`).
|
|
112
|
+
* **Two process-level side effects**: a stdout/stderr filter that strips
|
|
113
|
+
noisy `✔ Before # …` hook lines from cucumber's failure dump
|
|
114
|
+
(`WEBSHIP_FILTER_HOOK_LINES=off` to disable), and a `process.on('exit')`
|
|
115
|
+
hook that auto-generates the HTML report via `bin/generate-reports`
|
|
116
|
+
(`WEBSHIP_REPORT_DISABLE=1` to disable, `WEBSHIP_REPORT_ARGS` to pass
|
|
117
|
+
flags).
|
|
118
|
+
|
|
119
|
+
### 2.3 Config layering
|
|
120
|
+
|
|
121
|
+
`playwright.config.ts` (browser choice, launch args, context options) is
|
|
122
|
+
loaded by `webship.js` from `process.cwd()` — so a consumer project's own
|
|
123
|
+
copy wins. `cucumber.js` supplies `worldParameters` (launch URL, wait
|
|
124
|
+
padding, selector registry + files + breakpoints, screenshot, video,
|
|
125
|
+
and javascript-error settings). Resolution order everywhere is
|
|
126
|
+
**env var → `worldParameters` → built-in default**; follow that order in
|
|
127
|
+
any new option.
|
|
128
|
+
|
|
129
|
+
### 2.4 Error contract — tester-facing, not developer-facing
|
|
130
|
+
|
|
131
|
+
Risky locator work is wrapped and re-thrown through `friendly()`, which
|
|
132
|
+
renders `Could not <action> "<target>". / Why: <humanize(cause)> /
|
|
133
|
+
Hint: …` and sets `err.stack` to that body so cucumber prints no JS stack.
|
|
134
|
+
`humanize()` maps ~20 Playwright/Node/HTTP patterns to plain English.
|
|
135
|
+
`action.steps.js`'s `actOrExplain(label, target, fn)` is the reference
|
|
136
|
+
wrapper — copy that shape for new interaction steps. Never let a raw
|
|
137
|
+
Playwright error reach the tester.
|
|
138
|
+
|
|
139
|
+
### 2.5 Named selector registry
|
|
140
|
+
|
|
141
|
+
`selectors.steps.js` owns the registry. Selectors resolve **css first,
|
|
142
|
+
then xpath** (auto-prefixed `xpath=`). Three registration paths: inline
|
|
143
|
+
step, bulk data table, or JSON files listed in
|
|
144
|
+
`worldParameters.selectors.files` (loaded from `filesPath`). 26 presets
|
|
145
|
+
ship in `tests/selectors/` (14 CMS admin skins, 9 CSS frameworks, generic
|
|
146
|
+
front/back-end/homepage), normalised against `_canonical-keys.json`. Registry keys
|
|
147
|
+
are also what the human-language steps read — `Then I see main nav above
|
|
148
|
+
breadcrumb`, `When I click primary button` — which is why canonical key
|
|
149
|
+
names matter more than they look.
|
|
150
|
+
|
|
151
|
+
### 2.6 Visual regression lives outside this repo
|
|
152
|
+
|
|
153
|
+
The Diffy step-pack was extracted to its own plugin,
|
|
154
|
+
[`diffy-steps`](https://github.com/webship/diffy-steps). webship-js no
|
|
155
|
+
longer ships `tests/step-definitions-diffy/`, the `diffy`
|
|
156
|
+
`worldParameters` block, or the mock Diffy API. Consumers install the
|
|
157
|
+
plugin and add `node_modules/@webship-js/diffy-steps/tests/step-definitions/**/*.js`
|
|
158
|
+
to their own `require:` list. Nothing in this repo depends on it — the
|
|
159
|
+
steps only ever used `@cucumber/cucumber`, `axios`, and Node built-ins.
|
|
160
|
+
Treat any `diffy` question as a `diffy-steps` question.
|
|
161
|
+
|
|
162
|
+
### 2.7 CI
|
|
163
|
+
|
|
164
|
+
Fifteen provider configs at the repo root (`.github/workflows/`,
|
|
165
|
+
`.gitlab-ci.yml`, `.circleci/`, `azure-pipelines.yml`,
|
|
166
|
+
`bitbucket-pipelines.yml`, `buildspec.yml`, `cloudbuild.yaml`,
|
|
167
|
+
`codefresh.yml`, `.drone.yml`, `Jenkinsfile`, `.semaphore/`, `.teamcity/`,
|
|
168
|
+
`bamboo-specs/`, `.harness/`, `.travis.yml`). They all run the same shape: install →
|
|
169
|
+
`npx playwright install` → `npm start &` → `npm test`. Change one, change
|
|
170
|
+
them all, and update `docs/16-ci-cd.md`.
|
|
171
|
+
|
|
172
|
+
## 3. Communication & change rules
|
|
17
173
|
|
|
18
174
|
1. **Never commit on the user's behalf.** The user always invokes git
|
|
19
175
|
commits manually. AI work stays uncommitted unless asked.
|
|
@@ -27,20 +183,23 @@ them. Treat webship-js as the source of truth.
|
|
|
27
183
|
restructure a step / selector / configuration option, update the matching
|
|
28
184
|
page under `docs/` in the same turn. Specifically:
|
|
29
185
|
* New / removed step → update `docs/04-step-reference.md`.
|
|
30
|
-
* New step file → add it to the source layout block in `docs/README.md
|
|
186
|
+
* New step file → add it to the source layout block in `docs/README.md`
|
|
187
|
+
(which carries per-file step counts — keep them accurate).
|
|
31
188
|
* Topic-level addition (auth, network, clock, …) → add or refresh the
|
|
32
189
|
dedicated page (`docs/07-auth-state.md`, `docs/06-network-and-dialogs.md`,
|
|
33
190
|
etc.).
|
|
34
191
|
* Selector preset added under `tests/selectors/` → add to the table in
|
|
35
192
|
`docs/03-selector-registry.md`.
|
|
193
|
+
* New config key → `cucumber.js` comment, `bin/init-webship.js`
|
|
194
|
+
template, and `docs/global-settings.md`.
|
|
36
195
|
5. **Backups.** When the user says "backup" or asks for a versioned zip,
|
|
37
196
|
bump the patch version in `package.json` and produce
|
|
38
|
-
|
|
197
|
+
`~/workspace/products/webship-js-<version>.zip`. Excludes:
|
|
39
198
|
`node_modules/`, `tests/reports/`, `screenshots/`, `.git/`.
|
|
40
199
|
|
|
41
|
-
##
|
|
200
|
+
## 4. Step definition rules
|
|
42
201
|
|
|
43
|
-
###
|
|
202
|
+
### 4.1 Phrasing
|
|
44
203
|
|
|
45
204
|
* Every step MUST support the pronoun prefix `(I |we )*`. Use a regex
|
|
46
205
|
pattern, not a Cucumber Expression with `'I ...'`, for any step where the
|
|
@@ -54,7 +213,7 @@ them. Treat webship-js as the source of truth.
|
|
|
54
213
|
product names in step phrasings or examples. Use neutral placeholders
|
|
55
214
|
(`example`, `Sample title`, `test-runner`).
|
|
56
215
|
|
|
57
|
-
###
|
|
216
|
+
### 4.2 JSDoc block — required for every step
|
|
58
217
|
|
|
59
218
|
Every step definition MUST be preceded by a JSDoc block with:
|
|
60
219
|
|
|
@@ -69,10 +228,12 @@ Every step definition MUST be preceded by a JSDoc block with:
|
|
|
69
228
|
strings unless the step accepts a doc string. Avoid quotes-within-quotes
|
|
70
229
|
Gherkin in examples.
|
|
71
230
|
|
|
72
|
-
|
|
73
|
-
|
|
231
|
+
Audit the examples by walking every JSDoc `Example #N:` line, stripping the
|
|
232
|
+
Gherkin keyword, and confirming the remainder matches the step regex. Keep
|
|
233
|
+
mismatches at zero. (Past sessions used a throwaway `audit-examples.js`
|
|
234
|
+
for this; write it into the scratchpad, not the repo.)
|
|
74
235
|
|
|
75
|
-
###
|
|
236
|
+
### 4.3 No duplicate logic
|
|
76
237
|
|
|
77
238
|
Before adding a step, search existing files. Identical Playwright calls
|
|
78
239
|
under different phrasings ARE allowed when the phrasings target different
|
|
@@ -80,59 +241,70 @@ audiences (e.g. `I hover over "X"` versus `I hover over the element "X"`).
|
|
|
80
241
|
True duplicate logic — same code, same conceptual scope — must be merged
|
|
81
242
|
or deleted.
|
|
82
243
|
|
|
83
|
-
###
|
|
244
|
+
### 4.4 Do NOT merge
|
|
84
245
|
|
|
85
246
|
Some pairs look similar but cover different domains. NEVER merge:
|
|
86
247
|
|
|
87
|
-
|
|
|
248
|
+
| Pair | Domain boundary |
|
|
88
249
|
| --- | --- |
|
|
89
|
-
| `modal.steps.js` | HTML modal
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
250
|
+
| `modal.steps.js` vs `dialog.steps.js` | HTML modal overlay (`role="dialog"`, `.modal`) vs native browser alert / confirm / prompt. |
|
|
251
|
+
| `field.steps.js` vs `form.steps.js` | CSS-selector field control vs label / placeholder / name form fills. |
|
|
252
|
+
| `assertion.steps.js` vs `web-first.steps.js` | Single-snapshot page assertions vs auto-retrying matchers (`within N seconds`). |
|
|
253
|
+
| `xml.steps.js` vs `yaml.steps.js` | Different parsers, different path conventions. |
|
|
254
|
+
| `api.steps.js` vs `rest.steps.js` | Long form (header + body table) vs short-form REST. |
|
|
255
|
+
| `element.steps.js` vs `input.steps.js` | Element-scoped (`the element "X"`) vs short pointer (`"X"`). |
|
|
95
256
|
|
|
96
|
-
##
|
|
257
|
+
## 5. File organisation
|
|
258
|
+
|
|
259
|
+
413 built-in steps across 36 step files. Cucumber auto-loads every
|
|
260
|
+
`*.steps.js` in `tests/step-definitions/`.
|
|
97
261
|
|
|
98
262
|
```
|
|
99
263
|
tests/step-definitions/
|
|
100
|
-
├── webship.js # World, hooks, init script, shared helpers
|
|
101
|
-
├──
|
|
102
|
-
├── action.steps.js
|
|
103
|
-
├──
|
|
104
|
-
├── assertion.steps.js # see / not see, in row, in element, response, count
|
|
105
|
-
├──
|
|
106
|
-
├──
|
|
107
|
-
├──
|
|
108
|
-
├──
|
|
109
|
-
├──
|
|
110
|
-
├──
|
|
111
|
-
├──
|
|
112
|
-
├──
|
|
113
|
-
├──
|
|
114
|
-
├──
|
|
115
|
-
├──
|
|
116
|
-
├──
|
|
117
|
-
├──
|
|
118
|
-
├──
|
|
119
|
-
├──
|
|
120
|
-
├──
|
|
121
|
-
├──
|
|
122
|
-
├──
|
|
123
|
-
├──
|
|
124
|
-
├──
|
|
125
|
-
├──
|
|
126
|
-
├──
|
|
127
|
-
├──
|
|
128
|
-
├──
|
|
129
|
-
├──
|
|
130
|
-
├──
|
|
131
|
-
├── table.steps.js
|
|
132
|
-
├──
|
|
133
|
-
├──
|
|
134
|
-
├──
|
|
135
|
-
|
|
264
|
+
├── webship.js # World, hooks, init script, shared helpers — see §2.2. Not a steps file.
|
|
265
|
+
├── a11y.steps.js (26) # axe-core WCAG audits + POUR hygiene probes (axe loaded lazily)
|
|
266
|
+
├── action.steps.js (7) # press / click / follow / attach file (actOrExplain lives here)
|
|
267
|
+
├── api.steps.js (22) # REST long form — base URL, headers, query, body, JSON Pointer
|
|
268
|
+
├── assertion.steps.js (14) # see / not see, in row, in element, response, count
|
|
269
|
+
├── auth.steps.js (3) # storageState save / restore / clear
|
|
270
|
+
├── clock.steps.js (7) # page.clock — install / advance / pause / set
|
|
271
|
+
├── cookie.steps.js (12) # cookie exists / equals / contains
|
|
272
|
+
├── debug.steps.js (2) # print URL / last response
|
|
273
|
+
├── dialog.steps.js (8) # native alert / confirm / prompt handlers
|
|
274
|
+
├── element.steps.js (19) # focus / scroll-to / dispatch / count / position
|
|
275
|
+
├── field.steps.js (27) # field, checkbox, radio, select-list state assertions
|
|
276
|
+
├── file-download.steps.js (8) # download capture + filename / mime / path assertions
|
|
277
|
+
├── form.steps.js (13) # fill / select / additionally select / check / uncheck / radio
|
|
278
|
+
├── iframe.steps.js (10) # frameLocator switch + frame-scoped interactions
|
|
279
|
+
├── input.steps.js (9) # hover / drag / dbl-click / right-click / tap / viewport size
|
|
280
|
+
├── javascript.steps.js (4) # JS error tracking + assertion (warn / fail / off)
|
|
281
|
+
├── keyboard.steps.js (4) # single key + combos with alias normalisation
|
|
282
|
+
├── link.steps.js (9) # href / title / target / rel assertions
|
|
283
|
+
├── metatag.steps.js (3) # <meta> description / keywords / OG / Twitter
|
|
284
|
+
├── modal.steps.js (9) # HTML modal visibility / content / interactions
|
|
285
|
+
├── navigation.steps.js (11) # anonymous user, homepage, paths, history, URL assertions
|
|
286
|
+
├── network.steps.js (10) # route stubs / blocks / delays / offline
|
|
287
|
+
├── path.steps.js (8) # URL path / query parameter / fragment
|
|
288
|
+
├── response.steps.js (4) # response header inspection
|
|
289
|
+
├── responsive.steps.js (5) # named breakpoints + explicit viewport
|
|
290
|
+
├── rest.steps.js (5) # REST short form
|
|
291
|
+
├── screenshot.steps.js (6) # manual + auto-on-failure + per-step capture
|
|
292
|
+
├── scroll.steps.js (12) # ALL scroll phrasings (page + scoped element)
|
|
293
|
+
├── selectors.steps.js (24) # named CSS / XPath registry + position + human-language steps
|
|
294
|
+
├── storage.steps.js (9) # local storage + session storage
|
|
295
|
+
├── table.steps.js (8) # data-table row / column assertions
|
|
296
|
+
├── video.steps.js (4) # start / stop / save webm recording
|
|
297
|
+
├── wait.steps.js (21) # ALL wait phrasings (BBR — see §6)
|
|
298
|
+
├── web-first.steps.js (12) # auto-retrying state matchers
|
|
299
|
+
├── xml.steps.js (20) # XPath equals / contains / count / attr
|
|
300
|
+
└── yaml.steps.js (38) # multi-doc, types, numerics, JSON Schema, diff
|
|
301
|
+
|
|
302
|
+
tests/features/ # 71 .feature files
|
|
303
|
+
tests/selectors/ # 26 JSON presets + _canonical-keys.json
|
|
304
|
+
tests/assets/ # upload fixtures (pdf, png)
|
|
305
|
+
examples/ # static HTML fixtures served by `npm start`
|
|
306
|
+
bin/ # init-webship / postinstall / generate-reports
|
|
307
|
+
docs/ # 17 numbered guides + mirrored reference pages
|
|
136
308
|
```
|
|
137
309
|
|
|
138
310
|
When you add a new step, place it in the file whose topic matches. Do NOT
|
|
@@ -140,7 +312,7 @@ spawn a new file unless the topic is genuinely orthogonal to every
|
|
|
140
312
|
existing file. New file → mention it in `docs/README.md` AND update the
|
|
141
313
|
table above.
|
|
142
314
|
|
|
143
|
-
##
|
|
315
|
+
## 6. Behavior-Based Robotics (BBR) wait policy
|
|
144
316
|
|
|
145
317
|
Static `sleep` is forbidden in step bodies. Every wait step uses
|
|
146
318
|
`smartSettle(page, budget)` from `webship.js`, which composites:
|
|
@@ -152,15 +324,17 @@ Static `sleep` is forbidden in step bodies. Every wait step uses
|
|
|
152
324
|
5. `window.__webshipPendingTimers === 0` (custom `setTimeout` counter)
|
|
153
325
|
6. `Date.now() - window.__webshipLastMutation >= 250 ms` (DOM-quiet)
|
|
154
326
|
|
|
155
|
-
|
|
156
|
-
`
|
|
327
|
+
Conditions 4/5/6 are evaluated atomically in one `waitForFunction`, so a
|
|
328
|
+
late-firing `setTimeout` that mutates the DOM re-arms the wait.
|
|
157
329
|
|
|
158
330
|
Auto-settle hook: `AfterStep` runs `smartSettle(page, 1500)` after every
|
|
159
|
-
step whose text matches `STATE_MUTATING_STEP` (click / press / fill /
|
|
160
|
-
|
|
161
|
-
|
|
331
|
+
step whose text matches `STATE_MUTATING_STEP` (click / press / fill /
|
|
332
|
+
select / check / attach / reload / navigate / …). This is what makes
|
|
333
|
+
`When I click "X" Then I should see "Y"` work without an explicit wait.
|
|
334
|
+
Disable per-run with `WEBSHIP_AUTO_SETTLE=off`. If a wait is flaky only in
|
|
335
|
+
CI, raise the budget — never add a static sleep.
|
|
162
336
|
|
|
163
|
-
##
|
|
337
|
+
## 7. Selector registry
|
|
164
338
|
|
|
165
339
|
* Selectors live in `tests/selectors/*.json`, two top-level keys: `css`,
|
|
166
340
|
`xpath`.
|
|
@@ -175,35 +349,23 @@ an explicit wait. Disable per-run with `WEBSHIP_AUTO_SETTLE=off`.
|
|
|
175
349
|
* Custom modal selector: every preset SHOULD expose a `modal` key. The
|
|
176
350
|
modal helpers in `webship.js` use it before falling back to
|
|
177
351
|
`[role="dialog"], dialog`.
|
|
352
|
+
* When a UI change breaks tests, fix the selector in the JSON preset —
|
|
353
|
+
not the feature files.
|
|
178
354
|
|
|
179
|
-
##
|
|
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
|
|
355
|
+
## 8. Tests must stay green
|
|
196
356
|
|
|
197
357
|
Before declaring a task done:
|
|
198
358
|
|
|
199
|
-
1.
|
|
200
|
-
2. Run
|
|
359
|
+
1. `npm install` if `node_modules/` is absent (it is not committed).
|
|
360
|
+
2. Run `npx cucumber-js --dry-run` — no ambiguity, no undefined steps.
|
|
361
|
+
3. Run the full suite with the fixture server up:
|
|
362
|
+
`npm start &` then `LAUNCH_URL=http://localhost:8080 npx cucumber-js`.
|
|
201
363
|
All scenarios must pass.
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
364
|
+
4. Fix any mismatch between JSDoc examples and step patterns (§4.2).
|
|
365
|
+
5. Report honestly: if you could not run the suite, say so rather than
|
|
366
|
+
implying green.
|
|
205
367
|
|
|
206
|
-
##
|
|
368
|
+
## 9. AI agent wisdom — see [docs/12-ai-agent-guide.md](docs/12-ai-agent-guide.md)
|
|
207
369
|
|
|
208
370
|
That page distils the canonical guidance from *Webship-js-Recipes v1.0.30*
|
|
209
371
|
into one reference. Internalise these:
|
|
@@ -223,14 +385,19 @@ into one reference. Internalise these:
|
|
|
223
385
|
answered in `Feature:` description before any `Scenario:` lines.
|
|
224
386
|
* **DAMP / KISS / YAGNI / MMF.** Self-contained scenarios, simplest
|
|
225
387
|
test that fails, no speculative features, smallest piece of value.
|
|
226
|
-
* **Golden rules** —
|
|
227
|
-
|
|
228
|
-
behaviour per scenario.
|
|
388
|
+
* **Golden rules** — top three: test behaviour not implementation, wait
|
|
389
|
+
for events not time, one behaviour per scenario.
|
|
229
390
|
* **AI pitfalls.** Over-trusting output, implementation tests, missing
|
|
230
391
|
edge cases, false confidence. Mitigation: AI generates, humans
|
|
231
392
|
validate against business requirements.
|
|
232
393
|
|
|
233
|
-
|
|
394
|
+
Tag conventions live in `docs/15-tag-conventions.md` — `@critical`,
|
|
395
|
+
`@smoke`, `@auth`, `@security`, `@a11y`, `@i18n`, `@perf`, `@flaky`,
|
|
396
|
+
`@wip`, `@desktop`/`@mobile`, `@external`, `@auth-setup`, plus the
|
|
397
|
+
recording tags `@video` / `@no-video` and the JS-error tags `@js-fail` /
|
|
398
|
+
`@js-warn` / `@js-off`.
|
|
399
|
+
|
|
400
|
+
## 10. AI prompts — concrete templates
|
|
234
401
|
|
|
235
402
|
When asked to do common tasks, use these templates. They are battle-tested.
|
|
236
403
|
|
|
@@ -244,7 +411,7 @@ Generate one Scenario per Operations item.
|
|
|
244
411
|
Tag each scenario with the relevant Norm / Safeguard category
|
|
245
412
|
(@critical, @auth, @a11y, @security, @i18n).
|
|
246
413
|
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 §
|
|
414
|
+
and place it in the file whose topic matches (see CLAUDE.md §5).
|
|
248
415
|
Run npx cucumber-js tests/features/<name>.feature when done.
|
|
249
416
|
```
|
|
250
417
|
|
|
@@ -278,6 +445,7 @@ Re-run. Iterate until green. Commit prompt + code + selector changes together.
|
|
|
278
445
|
```
|
|
279
446
|
Re-run with HEADLESS=false SLOW_MO=800 to watch what really happens.
|
|
280
447
|
Look at screenshots/failed_*.png for the moment of failure.
|
|
448
|
+
Record it: WEBSHIP_VIDEO=on npx cucumber-js <path> (or tag the scenario @video).
|
|
281
449
|
Replace any wait Ns with an edge wait:
|
|
282
450
|
wait until the URL contains "..."
|
|
283
451
|
wait for "selector" to appear
|
|
@@ -287,27 +455,79 @@ If the bug is timing only in CI, bump the budget on the smart wait,
|
|
|
287
455
|
do NOT add static sleeps.
|
|
288
456
|
```
|
|
289
457
|
|
|
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
458
|
### Rules of engagement (for the prompt itself)
|
|
300
459
|
|
|
301
460
|
When the user gives an ambiguous task, ASK before guessing. Specifically:
|
|
302
461
|
|
|
303
|
-
- "Where should this step live?" — pick the file whose topic matches §
|
|
462
|
+
- "Where should this step live?" — pick the file whose topic matches §5.
|
|
304
463
|
- "Should this be a custom step or compose existing ones?" — prefer
|
|
305
464
|
composing existing steps inside a feature scenario.
|
|
306
465
|
- "Should I commit?" — never. The user always commits manually.
|
|
307
|
-
- "Should I update docs?" — yes, in the same change. See §
|
|
466
|
+
- "Should I update docs?" — yes, in the same change. See §3.4.
|
|
308
467
|
- "Should I bump the version + zip?" — only when the user says "backup".
|
|
309
468
|
|
|
310
|
-
##
|
|
469
|
+
## 11. Local AI agents & skills that drive webship-js
|
|
470
|
+
|
|
471
|
+
Seven local Claude Code definitions target webship-js. They are **not**
|
|
472
|
+
part of this repo (`.gitignore` excludes `.claude`) — they are authored in
|
|
473
|
+
the workspace repos and installed into `~/.claude/`:
|
|
474
|
+
|
|
475
|
+
| Source of truth | Installed to | Sync |
|
|
476
|
+
| --- | --- | --- |
|
|
477
|
+
| `~/workspace/agents/*.md` | `~/.claude/agents/` | `agents/cmd-tool-sync-agents.sh --install` (also mirrors the shared `webship/ai-agents` repo) |
|
|
478
|
+
| `~/workspace/skills/<name>/SKILL.md` | `~/.claude/skills/` | `skills/cmd-tool-sync-skills.sh` |
|
|
479
|
+
|
|
480
|
+
### Agents
|
|
481
|
+
|
|
482
|
+
| Agent | Model | Scope |
|
|
483
|
+
| --- | --- | --- |
|
|
484
|
+
| `agent-webship-js` | opus | The full specialist. Scaffold (Node.js or DDEV) → author `.feature` files → write custom steps → run → debug → HTML/PDF report. Carries a distilled copy of the whole step catalog, the BBR/selector/tag sections, the 20-recipe cookbook, Varbase learnings, and recipes AI-1…AI-5. Use for anything non-trivial. |
|
|
485
|
+
| `webship-ai-agent` | sonnet | The loop-until-green worker for a consumer project: read available steps → write/fix scenarios → run → fix root cause → iterate to zero failures. Lighter, autonomous, Drupal/DDEV-flavoured (`NN-NN-NN-name.feature`, `https://<project>.ddev.site`). |
|
|
486
|
+
|
|
487
|
+
### Skills (slash commands)
|
|
488
|
+
|
|
489
|
+
| Skill | Does |
|
|
490
|
+
| --- | --- |
|
|
491
|
+
| `/webship-js-init` | Scaffold a test project for a URL, or `--ddev` for the `ddev-webship-js` add-on. Idempotent; never clobbers `cucumber.js` without `--force`. |
|
|
492
|
+
| `/webship-js-create` | Author `tests/features/<page>--<category>.feature` for a page or flow — desktop + mobile, web-first assertions, named selectors, tags. |
|
|
493
|
+
| `/webship-js-run` | Run the suite (tag expression or feature path), generate HTML/PDF, and return a root-cause summary per failure. |
|
|
494
|
+
| `/webship-js-audit` | Lint features + custom steps against the documented anti-patterns — sleep-driven waits, god scenarios, brittle selectors, implementation testing, premature custom steps, leaked module state. Output is `file:line — severity — pattern — fix`. |
|
|
495
|
+
| `/webship-js-steps` | Step catalog reference, filterable by category. |
|
|
496
|
+
|
|
497
|
+
`barmoog-webship-js-{init,create,run,audit,steps}` are the same five skills
|
|
498
|
+
hard-targeted at a Barmoog Odoo 18.0 instance. Don't edit them for
|
|
499
|
+
webship-js changes — fix the `webship-js-*` originals and let the Barmoog
|
|
500
|
+
copies be re-derived.
|
|
501
|
+
|
|
502
|
+
### What this means when working *inside* this repo
|
|
503
|
+
|
|
504
|
+
1. **Every one of them reads `node_modules/webship-js/…` as the source of
|
|
505
|
+
truth.** That path does not exist here — this *is* the package. Translate:
|
|
506
|
+
`node_modules/webship-js/tests/step-definitions/` → `tests/step-definitions/`,
|
|
507
|
+
`node_modules/webship-js/docs/` → `docs/`,
|
|
508
|
+
`node_modules/webship-js/bin/` → `bin/`.
|
|
509
|
+
Running one of these skills unmodified in this repo will find nothing and
|
|
510
|
+
fall back to fetching from GitHub — i.e. it will read the *published*
|
|
511
|
+
step regex, not your uncommitted change. Read the local files directly
|
|
512
|
+
instead.
|
|
513
|
+
2. **Step regex, JSDoc examples, and `docs/` are their API.** The agents are
|
|
514
|
+
explicitly instructed to verify phrasing against the installed
|
|
515
|
+
`<category>.steps.js` and its JSDoc before recommending a step. A
|
|
516
|
+
rename here silently changes what every agent tells every user — which
|
|
517
|
+
is the real reason for the docs rule in §3.4 and the ≥5-examples rule
|
|
518
|
+
in §4.2.
|
|
519
|
+
3. **Known drift to be aware of, not to "fix" here:** the agents and the
|
|
520
|
+
`/webship-js-run` skill reference a `worldParameters.users` registry and
|
|
521
|
+
an auth helper built on it. There is no `users` key in this repo's
|
|
522
|
+
`cucumber.js` or in `bin/init-webship.js` — it is a Varbase-project
|
|
523
|
+
convention layered on top. If a user asks about `users`, say so rather
|
|
524
|
+
than adding the key on the agents' say-so.
|
|
525
|
+
4. **Guardrails they already carry** (so don't re-litigate them): never
|
|
526
|
+
commit; never overwrite a user's `.feature` or `cucumber.js` without
|
|
527
|
+
explicit consent; verify a step exists before recommending it; when
|
|
528
|
+
reality diverges from the prompt, fix the prompt first.
|
|
529
|
+
|
|
530
|
+
## 12. Avoid
|
|
311
531
|
|
|
312
532
|
* Comments that describe WHAT the code does — names already do that.
|
|
313
533
|
* Backwards-compatibility shims for unused code paths — delete unused code.
|
|
@@ -315,3 +535,5 @@ When the user gives an ambiguous task, ASK before guessing. Specifically:
|
|
|
315
535
|
* Adding feature flags for hypothetical future requirements.
|
|
316
536
|
* `// removed` comments — git history is the record, not the file.
|
|
317
537
|
* Replacing existing selectors with synonyms when canonical keys exist.
|
|
538
|
+
* Raw Playwright errors surfacing to testers — always go through
|
|
539
|
+
`friendly()` / `humanize()`.
|
package/Jenkinsfile
CHANGED
|
File without changes
|
package/azure-pipelines.yml
CHANGED
|
File without changes
|
package/bamboo-specs/bamboo.yml
CHANGED
|
File without changes
|
package/bin/init-webship.js
CHANGED
|
@@ -14,7 +14,6 @@ const CUCUMBER_JS = `module.exports = {
|
|
|
14
14
|
requireModule: ['ts-node/register'],
|
|
15
15
|
require: [
|
|
16
16
|
'node_modules/webship-js/tests/step-definitions/**/*.js', // Webship-js core step definitions (auto HTML report on exit; disable: WEBSHIP_REPORT_DISABLE=1).
|
|
17
|
-
// 'node_modules/webship-js/tests/step-definitions-diffy/**/*.js', // Diffy step definitions (optional).
|
|
18
17
|
'tests/step-definitions/**/*.js', // Your custom step definitions.
|
|
19
18
|
],
|
|
20
19
|
paths: ['tests/features/**/*.feature'],
|
|
@@ -70,18 +69,6 @@ const CUCUMBER_JS = `module.exports = {
|
|
|
70
69
|
filenamePatternFailed: '{failed_prefix}{datetime}.{feature_file}.feature_{step_line}.{ext}',
|
|
71
70
|
infoTypes: '',
|
|
72
71
|
},
|
|
73
|
-
// Diffy visual-regression (optional). Uncomment and set apiKey / projectId to enable.
|
|
74
|
-
// diffy: {
|
|
75
|
-
// apiKey: '', // DIFFY_API_KEY
|
|
76
|
-
// projectId: 0, // DIFFY_PROJECT_ID
|
|
77
|
-
// breakpoints: '640,1200', // DIFFY_BREAKPOINTS
|
|
78
|
-
// windowHeight: 2000, // DIFFY_WINDOW_HEIGHT
|
|
79
|
-
// screenshotsDir: '', // DIFFY_SCREENSHOTS_DIR
|
|
80
|
-
// baseUrl: 'https://app.diffy.website/api/', // DIFFY_API_BASE_URL
|
|
81
|
-
// maxWait: 30, // DIFFY_MAX_WAIT (seconds)
|
|
82
|
-
// env1Url: '', // DIFFY_ENV1_URL
|
|
83
|
-
// env2Url: '', // DIFFY_ENV2_URL
|
|
84
|
-
// },
|
|
85
72
|
},
|
|
86
73
|
},
|
|
87
74
|
};
|
package/bin/postinstall.js
CHANGED
|
File without changes
|
package/buildspec.yml
CHANGED
|
File without changes
|
package/cloudbuild.yaml
CHANGED
|
File without changes
|
package/codefresh.yml
CHANGED
|
File without changes
|
package/cucumber.js
CHANGED
|
@@ -11,7 +11,6 @@ module.exports = {
|
|
|
11
11
|
requireModule: ['tsx/cjs'],
|
|
12
12
|
require: [
|
|
13
13
|
'tests/step-definitions/**/*.js',
|
|
14
|
-
'tests/step-definitions-diffy/**/*.js',
|
|
15
14
|
],
|
|
16
15
|
paths: ['tests/features/**/*.feature'],
|
|
17
16
|
format: [
|
|
@@ -121,17 +120,6 @@ module.exports = {
|
|
|
121
120
|
// Report collected errors at scenario end (default true).
|
|
122
121
|
afterScenario: true, // WEBSHIP_JS_ERROR_AFTER
|
|
123
122
|
},
|
|
124
|
-
diffy: {
|
|
125
|
-
apiKey: 'mock-key', // DIFFY_API_KEY
|
|
126
|
-
projectId: 1, // DIFFY_PROJECT_ID
|
|
127
|
-
breakpoints: '640,1200', // DIFFY_BREAKPOINTS
|
|
128
|
-
windowHeight: 2000, // DIFFY_WINDOW_HEIGHT
|
|
129
|
-
screenshotsDir: '', // DIFFY_SCREENSHOTS_DIR
|
|
130
|
-
baseUrl: 'http://127.0.0.1:3099/', // DIFFY_API_BASE_URL (mock server)
|
|
131
|
-
maxWait: 30, // DIFFY_MAX_WAIT (seconds)
|
|
132
|
-
env1Url: '', // DIFFY_ENV1_URL (custom env)
|
|
133
|
-
env2Url: '', // DIFFY_ENV2_URL (custom env)
|
|
134
|
-
},
|
|
135
123
|
},
|
|
136
124
|
},
|
|
137
125
|
};
|