webship-js 2.0.5 → 2.0.7

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 (196) hide show
  1. package/.drone.yml +0 -0
  2. package/.harness/webship-js-pipeline.yml +0 -0
  3. package/.semaphore/semaphore.yml +0 -0
  4. package/.teamcity/pom.xml +0 -0
  5. package/.teamcity/settings.kts +0 -0
  6. package/.travis.yml +0 -0
  7. package/AGENTS.md +1 -1
  8. package/CLAUDE.md +5 -5
  9. package/Jenkinsfile +0 -0
  10. package/azure-pipelines.yml +0 -0
  11. package/bamboo-specs/bamboo.yml +0 -0
  12. package/bin/generate-reports.js +0 -0
  13. package/bin/init-webship.js +9 -10
  14. package/bin/postinstall.js +0 -0
  15. package/buildspec.yml +0 -0
  16. package/cloudbuild.yaml +0 -0
  17. package/codefresh.yml +0 -0
  18. package/cucumber.js +3 -1
  19. package/docs/00-quick-start.md +0 -0
  20. package/docs/01-getting-started.md +0 -0
  21. package/docs/02-bbr-smart-waits.md +24 -1
  22. package/docs/03-selector-registry.md +0 -0
  23. package/docs/04-step-reference.md +4 -0
  24. package/docs/05-web-first-assertions.md +2 -0
  25. package/docs/06-network-and-dialogs.md +0 -0
  26. package/docs/07-auth-state.md +0 -0
  27. package/docs/08-clock-mocking.md +0 -0
  28. package/docs/09-api-testing.md +0 -0
  29. package/docs/10-accessibility.md +24 -3
  30. package/docs/11-debugging.md +0 -0
  31. package/docs/12-ai-agent-guide.md +0 -0
  32. package/docs/13-faq.md +0 -0
  33. package/docs/14-recipes-cookbook.md +0 -0
  34. package/docs/15-tag-conventions.md +0 -0
  35. package/docs/16-ci-cd.md +0 -0
  36. package/docs/README.md +2 -2
  37. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +0 -0
  38. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +0 -0
  39. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +0 -0
  40. package/docs/advanced-screenshots.md +0 -0
  41. package/docs/advanced-selectors.md +0 -0
  42. package/docs/api-step-definitions.md +0 -0
  43. package/docs/global-settings.md +5 -2
  44. package/docs/install-webship-js/ddev-webship-js.md +0 -0
  45. package/docs/step-definitions/given-i-am-anonymous-user.md +0 -0
  46. package/docs/step-definitions/given-i-am-homepage.md +0 -0
  47. package/docs/step-definitions/given-i-am-specific-page.md +0 -0
  48. package/docs/step-definitions/then-i-should-be.md +0 -0
  49. package/docs/step-definitions/then-i-should-see.md +6 -0
  50. package/docs/step-definitions/then-item-checkbox.md +0 -0
  51. package/docs/step-definitions/then-item-link-should-contain-url.md +0 -0
  52. package/docs/step-definitions/then-item-should-contain.md +0 -0
  53. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +0 -0
  54. package/docs/step-definitions/then-response-status-code-should-be-number.md +0 -0
  55. package/docs/step-definitions/then-value-radio-button-selected.md +0 -0
  56. package/docs/step-definitions/when-i-attach-file-file-name-element.md +0 -0
  57. package/docs/step-definitions/when-i-check-checkbox.md +0 -0
  58. package/docs/step-definitions/when-i-click-link.md +0 -0
  59. package/docs/step-definitions/when-i-click-operation-text-row.md +0 -0
  60. package/docs/step-definitions/when-i-fill.md +0 -0
  61. package/docs/step-definitions/when-i-go-homepage.md +0 -0
  62. package/docs/step-definitions/when-i-go-specific-page.md +0 -0
  63. package/docs/step-definitions/when-i-move-backward-one-page.md +0 -0
  64. package/docs/step-definitions/when-i-move-forward-one-page.md +0 -0
  65. package/docs/step-definitions/when-i-press-button.md +0 -0
  66. package/docs/step-definitions/when-i-reload-page.md +0 -0
  67. package/docs/step-definitions/when-i-scroll.md +0 -0
  68. package/docs/step-definitions/when-i-select-option-select-list.md +0 -0
  69. package/docs/step-definitions/when-i-select-radio-button-value.md +0 -0
  70. package/docs/step-definitions/when-i-uncheck-checkbox.md +0 -0
  71. package/docs/step-definitions/when-i-wait-ajax-finish.md +0 -0
  72. package/docs/step-definitions/when-i-wait.md +0 -0
  73. package/docs/step-definitions.md +0 -0
  74. package/examples/a11y.html +8 -0
  75. package/examples/account.html +0 -0
  76. package/examples/ajax-wait-examples.html +0 -0
  77. package/examples/cookies.html +0 -0
  78. package/examples/date.html +0 -0
  79. package/examples/dynamic-examples.html +0 -0
  80. package/examples/element-visibility.html +17 -0
  81. package/examples/element.html +0 -0
  82. package/examples/field.html +0 -0
  83. package/examples/keyboard.html +0 -0
  84. package/examples/links.html +0 -0
  85. package/examples/modal.html +0 -0
  86. package/examples/native-dialogs.html +22 -0
  87. package/examples/never-settles.html +32 -0
  88. package/examples/path.html +0 -0
  89. package/examples/table.html +0 -0
  90. package/examples/test--modal-dialogs.html +0 -0
  91. package/examples/test--when--i-additionally-select.html +0 -0
  92. package/examples/test--when--i-select-radio-button.html +0 -0
  93. package/examples/video-demo.html +0 -0
  94. package/examples/web-first-text.html +18 -0
  95. package/package.json +2 -2
  96. package/playwright.config.ts +0 -0
  97. package/tests/assets/test-document.pdf +0 -0
  98. package/tests/features/a11y.feature +22 -0
  99. package/tests/features/ajax-wait-examples.feature +0 -0
  100. package/tests/features/cookie.feature +0 -0
  101. package/tests/features/date.feature +0 -0
  102. package/tests/features/dynamic-content-examples.feature +0 -0
  103. package/tests/features/element.feature +0 -0
  104. package/tests/features/field.feature +0 -0
  105. package/tests/features/keyboard.feature +0 -0
  106. package/tests/features/link.feature +0 -0
  107. package/tests/features/modal-advanced-example.feature +0 -0
  108. package/tests/features/modal-basic-example.feature +0 -0
  109. package/tests/features/modal-error-handling-example.feature +0 -0
  110. package/tests/features/modal.feature +0 -0
  111. package/tests/features/path.feature +0 -0
  112. package/tests/features/pronoun-prefix-steps.feature +81 -0
  113. package/tests/features/response.feature +0 -0
  114. package/tests/features/responsive.feature +0 -0
  115. package/tests/features/smart-settle-budget.feature +12 -0
  116. package/tests/features/table.feature +0 -0
  117. package/tests/features/test--given--i-am-an-anonymous-user.feature +0 -0
  118. package/tests/features/test--then--i-save-screenshot.feature +0 -0
  119. package/tests/features/test--then--i-see-locator.feature +0 -0
  120. package/tests/features/test--then--i-should-not-see-an-element.feature +11 -1
  121. package/tests/features/test--then--i-should-see-n-elements.feature +0 -0
  122. package/tests/features/test--then--print-current-url-and-response.feature +0 -0
  123. package/tests/features/test--when--i-additionally-select.feature +0 -0
  124. package/tests/features/test--when--i-follow.feature +0 -0
  125. package/tests/features/test--when--i-select-radio-button.feature +0 -0
  126. package/tests/features/video.feature +0 -0
  127. package/tests/features/wait.feature +0 -0
  128. package/tests/features/web-first-text.feature +21 -0
  129. package/tests/features/yaml.feature +0 -0
  130. package/tests/reports/README.md +0 -0
  131. package/tests/selectors/_canonical-keys.json +0 -0
  132. package/tests/selectors/back-end-selectors.json +0 -0
  133. package/tests/selectors/cms-contentful-admin.json +0 -0
  134. package/tests/selectors/cms-craft-admin.json +0 -0
  135. package/tests/selectors/cms-drupal-cms-gin.json +0 -0
  136. package/tests/selectors/cms-drupal-core-claro.json +0 -0
  137. package/tests/selectors/cms-generic-admin.json +0 -0
  138. package/tests/selectors/cms-ghost-admin.json +0 -0
  139. package/tests/selectors/cms-joomla-admin.json +0 -0
  140. package/tests/selectors/cms-magento2-admin.json +0 -0
  141. package/tests/selectors/cms-prestashop-admin.json +0 -0
  142. package/tests/selectors/cms-shopify-admin.json +0 -0
  143. package/tests/selectors/cms-strapi-admin.json +0 -0
  144. package/tests/selectors/cms-typo3-admin.json +0 -0
  145. package/tests/selectors/cms-woocommerce-front.json +0 -0
  146. package/tests/selectors/cms-wordpress-admin.json +0 -0
  147. package/tests/selectors/framework-ant-design.json +0 -0
  148. package/tests/selectors/framework-bootstrap.json +0 -0
  149. package/tests/selectors/framework-bulma.json +0 -0
  150. package/tests/selectors/framework-chakra.json +0 -0
  151. package/tests/selectors/framework-foundation.json +0 -0
  152. package/tests/selectors/framework-material-ui.json +0 -0
  153. package/tests/selectors/framework-shadcn.json +0 -0
  154. package/tests/selectors/framework-tailwind.json +0 -0
  155. package/tests/selectors/framework-vuetify.json +0 -0
  156. package/tests/selectors/front-end-selectors.json +0 -0
  157. package/tests/selectors/homepage-selectors.json +0 -0
  158. package/tests/step-definitions/a11y.steps.js +340 -114
  159. package/tests/step-definitions/action.steps.js +0 -0
  160. package/tests/step-definitions/api.steps.js +0 -0
  161. package/tests/step-definitions/assertion.steps.js +18 -3
  162. package/tests/step-definitions/auth.steps.js +1 -1
  163. package/tests/step-definitions/clock.steps.js +2 -2
  164. package/tests/step-definitions/cookie.steps.js +0 -0
  165. package/tests/step-definitions/debug.steps.js +0 -0
  166. package/tests/step-definitions/dialog.steps.js +4 -4
  167. package/tests/step-definitions/element.steps.js +0 -0
  168. package/tests/step-definitions/field.steps.js +0 -0
  169. package/tests/step-definitions/file-download.steps.js +0 -0
  170. package/tests/step-definitions/form.steps.js +0 -0
  171. package/tests/step-definitions/iframe.steps.js +1 -1
  172. package/tests/step-definitions/input.steps.js +0 -0
  173. package/tests/step-definitions/javascript.steps.js +0 -0
  174. package/tests/step-definitions/keyboard.steps.js +0 -0
  175. package/tests/step-definitions/link.steps.js +0 -0
  176. package/tests/step-definitions/metatag.steps.js +0 -0
  177. package/tests/step-definitions/modal.steps.js +0 -0
  178. package/tests/step-definitions/navigation.steps.js +0 -0
  179. package/tests/step-definitions/network.steps.js +1 -1
  180. package/tests/step-definitions/path.steps.js +0 -0
  181. package/tests/step-definitions/response.steps.js +0 -0
  182. package/tests/step-definitions/responsive.steps.js +0 -0
  183. package/tests/step-definitions/rest.steps.js +0 -0
  184. package/tests/step-definitions/screenshot.steps.js +0 -0
  185. package/tests/step-definitions/scroll.steps.js +0 -0
  186. package/tests/step-definitions/selectors.steps.js +0 -0
  187. package/tests/step-definitions/storage.steps.js +0 -0
  188. package/tests/step-definitions/table.steps.js +0 -0
  189. package/tests/step-definitions/video.steps.js +0 -0
  190. package/tests/step-definitions/wait.steps.js +3 -3
  191. package/tests/step-definitions/web-first.steps.js +14 -3
  192. package/tests/step-definitions/webship.js +57 -20
  193. package/tests/step-definitions/xml.steps.js +1 -1
  194. package/tests/step-definitions/yaml.steps.js +1 -1
  195. package/tsconfig.json +0 -0
  196. package/videos/README.md +0 -0
package/.drone.yml CHANGED
File without changes
File without changes
File without changes
package/.teamcity/pom.xml CHANGED
File without changes
File without changes
package/.travis.yml CHANGED
File without changes
package/AGENTS.md CHANGED
@@ -109,7 +109,7 @@ step definitions. Critical takeaways:
109
109
 
110
110
  ## Source map
111
111
 
112
- Step definitions: `tests/step-definitions/` — 413 steps across 36
112
+ Step definitions: `tests/step-definitions/` — 417 steps across 36
113
113
  `*.steps.js` files, all auto-loaded. The `webship.js` file there is the
114
114
  single canonical entry point — World, hooks, init script, and shared
115
115
  helpers (`smartSettle`, `waitForPageLoad`, `buildSelector`, `gotoUrl`,
package/CLAUDE.md CHANGED
@@ -53,7 +53,7 @@ HEADLESS=false SLOW_MO=800 npx cucumber-js tests/features/x.feature # watch a
53
53
  ```
54
54
 
55
55
  Env vars: `LAUNCH_URL`, `BROWSER`, `HEADLESS`, `SLOW_MO`, `FORCE_COLOR`,
56
- `WEBSHIP_AUTO_SETTLE`, `WEBSHIP_REPORT_DISABLE`, `WEBSHIP_REPORT_ARGS`,
56
+ `WEBSHIP_AUTO_SETTLE`, `WEBSHIP_STEP_TIMEOUT`, `WEBSHIP_REPORT_DISABLE`, `WEBSHIP_REPORT_ARGS`,
57
57
  `WEBSHIP_FILTER_HOOK_LINES`, `WEBSHIP_SCREENSHOT_*`, `WEBSHIP_VIDEO*`,
58
58
  `WEBSHIP_JS_ERROR_*`, `WEBSHIP_SELECTORS_OFFSET`,
59
59
  `WEBSHIP_SELECTORS_BREAKPOINTS`, `DIFFY_*`. Every one of them mirrors a
@@ -87,7 +87,7 @@ Everything shared lives here; every `*.steps.js` does
87
87
  * **The World** (`PlaywrightWorld extends World`) — `page`, `context`,
88
88
  `playwrightBrowser`, `frame` (iframe scope), `launchUrl`, `minWaitTime`,
89
89
  `assetsFolder`, and the named-selector registries `__selectorsCss` /
90
- `__selectorsXpath`. `setDefaultTimeout(45s)` — deliberately above
90
+ `__selectorsXpath`. `setDefaultTimeout(45s)` (`WEBSHIP_STEP_TIMEOUT` overrides) — deliberately above
91
91
  Playwright's 30 s default so locator timeouts reach our try/catch
92
92
  wrappers and testers see a friendly message, not "function timed out".
93
93
  The 45 s in `cucumber.js` exists for the same reason; keep them aligned.
@@ -256,13 +256,13 @@ Some pairs look similar but cover different domains. NEVER merge:
256
256
 
257
257
  ## 5. File organisation
258
258
 
259
- 413 built-in steps across 36 step files. Cucumber auto-loads every
259
+ 417 built-in steps across 36 step files. Cucumber auto-loads every
260
260
  `*.steps.js` in `tests/step-definitions/`.
261
261
 
262
262
  ```
263
263
  tests/step-definitions/
264
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)
265
+ ├── a11y.steps.js (30) # axe-core WCAG audits + POUR hygiene probes (axe loaded lazily)
266
266
  ├── action.steps.js (7) # press / click / follow / attach file (actOrExplain lives here)
267
267
  ├── api.steps.js (22) # REST long form — base URL, headers, query, body, JSON Pointer
268
268
  ├── assertion.steps.js (14) # see / not see, in row, in element, response, count
@@ -299,7 +299,7 @@ tests/step-definitions/
299
299
  ├── xml.steps.js (20) # XPath equals / contains / count / attr
300
300
  └── yaml.steps.js (38) # multi-doc, types, numerics, JSON Schema, diff
301
301
 
302
- tests/features/ # 71 .feature files
302
+ tests/features/ # 73 .feature files
303
303
  tests/selectors/ # 26 JSON presets + _canonical-keys.json
304
304
  tests/assets/ # upload fixtures (pdf, png)
305
305
  examples/ # static HTML fixtures served by `npm start`
package/Jenkinsfile CHANGED
File without changes
File without changes
File without changes
File without changes
@@ -10,13 +10,14 @@ const packagePath = path.join(__dirname, '..');
10
10
 
11
11
  const CUCUMBER_JS = `module.exports = {
12
12
  default: {
13
- timeout: 30000,
14
- requireModule: ['ts-node/register'],
13
+ timeout: 30000, // Overridden by webship-js's setDefaultTimeout (45s); raise it with WEBSHIP_STEP_TIMEOUT.
14
+ requireModule: ['tsx/cjs'],
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
17
  'tests/step-definitions/**/*.js', // Your custom step definitions.
18
18
  ],
19
- paths: ['tests/features/**/*.feature'],
19
+ // FEATURES=tests/features/a.feature,tests/features/b.feature runs a subset.
20
+ paths: process.env.FEATURES ? process.env.FEATURES.split(',') : ['tests/features/**/*.feature'],
20
21
  format: [
21
22
  '@cucumber/pretty-formatter',
22
23
  'json:tests/reports/cucumber_report.json',
@@ -59,7 +60,7 @@ const CUCUMBER_JS = `module.exports = {
59
60
  },
60
61
  },
61
62
  screenshot: {
62
- dir: './screenshots',
63
+ dir: './tests/screenshots',
63
64
  purge: false,
64
65
  onFailed: true,
65
66
  onEveryStep: false,
@@ -100,8 +101,9 @@ interface PlaywrightConfig {
100
101
  const config: PlaywrightConfig = {
101
102
  browser,
102
103
  launchOptions: {
103
- headless: true,
104
- slowMo: 300,
104
+ headless: process.env.HEADLESS !== 'false',
105
+ // SLOW_MO env var: 0 in CI for speed, 800ms when watching headed runs.
106
+ slowMo: parseInt(process.env.SLOW_MO || (process.env.HEADLESS === 'false' ? '800' : '300'), 10),
105
107
  args: browser === 'chromium' ? chromiumArgs : [],
106
108
  },
107
109
  contextOptions: {
@@ -121,9 +123,6 @@ const TSCONFIG_JSON = {
121
123
  esModuleInterop: true,
122
124
  types: ['node'],
123
125
  },
124
- 'ts-node': {
125
- ignore: ['node_modules/(?!webship-js/)'],
126
- },
127
126
  };
128
127
 
129
128
  const FEATURE_SAMPLE = `Feature: Check the home page
@@ -304,7 +303,7 @@ function run(argv) {
304
303
  ensureDir(path.join(projectPath, 'tests', 'reports'));
305
304
  ensureDir(path.join(projectPath, 'tests', 'step-definitions'));
306
305
  ensureDir(path.join(projectPath, 'tests', 'selectors'));
307
- ensureDir(path.join(projectPath, 'screenshots'));
306
+ ensureDir(path.join(projectPath, 'tests', 'screenshots'));
308
307
 
309
308
  const assetResults = writeTextAssets(projectPath, opts);
310
309
  const tsconfigWritten = writeTsconfig(projectPath, opts);
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
@@ -3,7 +3,9 @@ module.exports = {
3
3
  // Cucumber step timeout must exceed Playwright's default 30s so the
4
4
  // try/catch wrappers in step files always see the Playwright error
5
5
  // first (and emit a friendly message) rather than cucumber's raw
6
- // "function timed out" stack.
6
+ // "function timed out" stack. The step definitions call
7
+ // setDefaultTimeout() on load, which wins over this value — raise it
8
+ // with WEBSHIP_STEP_TIMEOUT instead.
7
9
  timeout: 45000,
8
10
  // tsx/cjs registers a require() hook so cucumber-js can load both
9
11
  // `.js` and `.ts` step files with zero build step. If you ship only
File without changes
File without changes
@@ -21,7 +21,30 @@ __webshipAjaxCount === 0
21
21
  && (Date.now() - __webshipLastMutation) >= 250 ms
22
22
  ```
23
23
 
24
- …or when `budget` elapses, whichever comes first. Each phase is best-effort, so a slow network does not stall the others.
24
+ …or when `budget` elapses, whichever comes first.
25
+
26
+ ### How the budget is shared
27
+
28
+ Each phase is best-effort — a phase that times out is not a failure — and each
29
+ gets a **share of the budget** rather than "whatever is left":
30
+
31
+ | Phase | Share of the budget |
32
+ | --- | --- |
33
+ | `<body>` attached | 25% |
34
+ | `DOMContentLoaded` | 25% |
35
+ | `networkidle` | 50% |
36
+ | AJAX + pending timers + DOM quiet | 50% |
37
+
38
+ The shares add up to more than 100% on purpose: a phase that finishes early
39
+ hands its unspent time to the ones after it, and no phase is ever given more
40
+ than what is actually left. Capping `networkidle` matters, because on a page
41
+ with analytics, a chat widget or a self-rescheduling timer it never arrives —
42
+ uncapped it would eat the whole budget and starve the AJAX / pending-timer /
43
+ DOM-quiet probe, which is the phase that decides the answer.
44
+
45
+ `smartSettle` returns within `budget` even when nothing on the page ever
46
+ settles, and never hands Playwright a zero timeout (Playwright reads `0` as
47
+ "no timeout at all").
25
48
 
26
49
  ## Step phrasings
27
50
 
File without changes
@@ -302,11 +302,15 @@ This index lists every public step grouped by source file, with one Gherkin exam
302
302
  - *^user zoom should be allowed$* · Example: `Then user zoom should be allowed`
303
303
  - *^the page should pass an accessibility audit(?: at level "(A|AA|AAA)")?$* · Example: `Then the page should pass an accessibility audit`
304
304
  - *^the page should have no (critical|serious|moderate|minor) accessibility violations$* · Example: `Then the page should have no critical accessibility violations`
305
+ - *^the page should have no accessibility violations$* · Example: `Then the page should have no accessibility violations`
306
+ - *^the element "([^"]*)" should not violate the accessibility rule "([^"]*)"$* · Example: `Then the element "main" should not violate the accessibility rule "color-contrast"`
305
307
  - *^the element "([^"]*)" should pass an accessibility audit$* · Example: `Then the element "main" should pass an accessibility audit`
306
308
  - *^the page should pass an accessibility audit excluding "([^"]*)"$* · Example: `Then the page should pass an accessibility audit excluding "iframe.payment"`
307
309
  - *^the page should not violate the accessibility rule "([^"]*)"$* · Example: `Then the page should not violate the accessibility rule "color-contrast"`
308
310
  - *^(I |we )*print accessibility violations$* · Example: `Then I print accessibility violations`
309
311
  - *^the page should pass the accessibility rules "([^"]*)"$* · Example: `Then the page should pass the accessibility rules "image-alt, label"`
312
+ - *^the page should pass the full accessibility check(?: at level "(A|AA|AAA)")?$* · Example: `Then the page should pass the full accessibility check`
313
+ - *^(?:I |we )*print the full accessibility check$* · Example: `Then I print the full accessibility check`
310
314
 
311
315
  ### action.steps.js
312
316
 
@@ -52,6 +52,8 @@ Then "<sel>" should contain text "$99"
52
52
  Then "<sel>" should have value "alice@example.com"
53
53
  ```
54
54
 
55
+ `should have text` is the exact match: the element's text, trimmed. `should contain text` collapses every run of whitespace to one space, on the element's text and on the expected text, before it looks for the substring, so a line the markup wraps still matches.
56
+
55
57
  ## Attributes / classes
56
58
 
57
59
  ```gherkin
File without changes
File without changes
File without changes
File without changes
@@ -38,7 +38,9 @@ Then every image should have an alt attribute
38
38
  And every form field should have an accessible label
39
39
  ```
40
40
 
41
- `every image` allows empty `alt=""` (decorative) and `role="presentation"`. Missing alt fails.
41
+ `every image` allows empty `alt=""` (decorative), `role="presentation"` or `role="none"`, and an `aria-label`, `aria-labelledby` or `title`. Missing alt fails.
42
+
43
+ Every probe skips what assistive technology cannot reach: anything under `aria-hidden="true"`, `inert` or `hidden`, and anything with `display: none` or `visibility: hidden`. axe does the same, so a closed menu or an overlay scrim no longer fails a probe that axe passes.
42
44
 
43
45
  `every form field` counts as labelled when **any** of the following is true:
44
46
  - An `aria-label` attribute is present
@@ -119,6 +121,20 @@ Then the page should have a title
119
121
  | `user zoom should be allowed` | 1.4.4, 1.4.10 |
120
122
  | `required fields should be consistently marked` | 3.3.2 |
121
123
 
124
+ ## The full check, in one step
125
+
126
+ ```gherkin
127
+ Then the page should pass the full accessibility check
128
+ And the page should pass the full accessibility check at level "A"
129
+ Then I print the full accessibility check
130
+ ```
131
+
132
+ One step runs axe at the level (AA by default) and every structural probe in this file in a single pass: image alt, button and link names, field labels, iframe titles, positive tabindex, unresolved ARIA references, one h1, skipped heading levels, empty headings, main and navigation landmarks, page language, page title, zoom, and navigation landmarks sharing one name.
133
+
134
+ It reports every failure at once, not the first. A finding axe already named is not repeated by the probe that covers the same thing. The print form reports without failing, which is the way to see where a page stands before choosing a gate.
135
+
136
+ The skip link, focus, ARIA role and required-field steps are not part of it. Add them beside it when you need them.
137
+
122
138
  ## axe-core full audit
123
139
 
124
140
  ```gherkin
@@ -127,13 +143,17 @@ Then the page should pass an accessibility audit
127
143
  And the page should pass an accessibility audit at level "AAA"
128
144
  And the page should have no critical accessibility violations
129
145
  And the page should have no serious accessibility violations
146
+ And the page should have no accessibility violations
130
147
  And the element "main" should pass an accessibility audit
148
+ And the element "main" should not violate the accessibility rule "color-contrast"
131
149
  And the page should pass an accessibility audit excluding "iframe.payment"
132
150
  And the page should not violate the accessibility rule "color-contrast"
133
151
  And the page should pass the accessibility rules "image-alt, label, button-name"
134
152
  Then I print accessibility violations
135
153
  ```
136
154
 
155
+ The impact gate is a ladder. `no serious accessibility violations` fails on a serious **or** a critical violation, and `no minor` fails on any. Earlier releases matched each gate to its own level only, so a page with a critical violation passed the serious gate. A suite that gated on serious alone gets stricter on upgrade. `no accessibility violations` fails on any impact.
156
+
137
157
  Default audit level is **AA** — required by EU Web Accessibility
138
158
  Directive, US Section 508, UK PSBAR. Use `at level "AAA"` for stricter
139
159
  gates.
@@ -159,9 +179,10 @@ For an admin / authenticated UI where some third-party widgets are
159
179
  known-bad, gate on the impact-based step instead:
160
180
 
161
181
  ```gherkin
162
- Then the page should have no critical accessibility violations
163
- And the page should have no serious accessibility violations
182
+ Then the page should have no serious accessibility violations
164
183
  ```
165
184
 
185
+ One serious gate now covers critical too.
186
+
166
187
  Tag scenarios `@a11y` so CI can run the accessibility suite in
167
188
  isolation: `npx cucumber-js --tags "@a11y"`.
File without changes
File without changes
package/docs/13-faq.md CHANGED
File without changes
File without changes
File without changes
package/docs/16-ci-cd.md CHANGED
File without changes
package/docs/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Webship-js is a BDD-first browser-automation harness built on Playwright + Cucumber-js. Feature files in plain Gherkin; selectors that survive redesigns; smart waits that never sleep.
4
4
 
5
- **411 built-in steps** across **36 step files**. **288 example scenarios / 1,406 step executions** in the bundled suite, all green on chromium, firefox, and webkit.
5
+ **417 built-in steps** across **36 step files**. **288 example scenarios / 1,406 step executions** in the bundled suite, all green on chromium, firefox, and webkit.
6
6
 
7
7
  ## Reading order
8
8
 
@@ -74,7 +74,7 @@ webship-js/
74
74
  │ ├── selectors/ <— CMS / framework JSON presets
75
75
  │ └── step-definitions/ <— Built-in steps (auto-loaded)
76
76
  │ ├── webship.js # World setup, hooks, shared helpers (smartSettle, modal, selectors, date tokens)
77
- │ ├── a11y.steps.js (26) # axe-core audits + WCAG hygiene probes
77
+ │ ├── a11y.steps.js (30) # axe-core audits + WCAG hygiene probes
78
78
  │ ├── action.steps.js (7) # press / click / follow / attach
79
79
  │ ├── api.steps.js (22) # REST long form (base URL, headers, query, body, JSON Pointer)
80
80
  │ ├── assertion.steps.js (14) # see / not see, in row, in element, response, count
File without changes
File without changes
File without changes
@@ -15,9 +15,9 @@ This page documents every supported setting plus its env-var override.
15
15
  | Key | Type | Default | Notes |
16
16
  | --- | --- | --- | --- |
17
17
  | `timeout` | int (ms) | `30000` | Per-step timeout enforced by `setDefaultTimeout`. |
18
- | `requireModule` | array | `['ts-node/register']` | TypeScript runtime support. |
18
+ | `requireModule` | array | `['tsx/cjs']` | TypeScript runtime support. |
19
19
  | `require` | array | step-definition globs | Files Cucumber-js loads at startup. |
20
- | `paths` | array | `['tests/features/**/*.feature']` | Where to find feature files. |
20
+ | `paths` | array | `['tests/features/**/*.feature']` | Where to find feature files. The scaffolded `cucumber.js` also reads `FEATURES`, comma-separated: `FEATURES=tests/features/a.feature,tests/features/b.feature`. |
21
21
  | `format` | array | pretty + JSON report | Output formatters. |
22
22
  | `formatOptions` | object | colour theme | Pretty-formatter colours. |
23
23
  | `worldParameters` | object | (sections below) | Everything passed to the Playwright World. |
@@ -132,6 +132,8 @@ screenshot: {
132
132
  | `filenamePatternFailed` | `{failed_prefix}...` | `WEBSHIP_SCREENSHOT_PATTERN_FAIL` |
133
133
  | `infoTypes` | `''` | `WEBSHIP_SCREENSHOT_INFO_TYPES` (e.g. `"url,feature,step,datetime"`) |
134
134
 
135
+ `init-webship-js` writes `dir: './tests/screenshots'` in the scaffolded `cucumber.js`, beside `tests/reports/`.
136
+
135
137
  Filename pattern tokens: `{datetime}`, `{date}`, `{time}`, `{feature_file}`,
136
138
  `{feature}`, `{scenario}`, `{step_line}`, `{ext}`, `{failed_prefix}`,
137
139
  `{url}`, `{host}`, `{path}`.
@@ -222,6 +224,7 @@ const config = {
222
224
  | Env var | Effect |
223
225
  | --- | --- |
224
226
  | `WEBSHIP_AUTO_SETTLE` | Set to `off` to disable the BBR auto-settle hook (`smartSettle(page, 1500)` after every state-changing step). |
227
+ | `WEBSHIP_STEP_TIMEOUT` | Cucumber step timeout in milliseconds. Defaults to `45000`. webship-js calls `setDefaultTimeout()` when its step definitions load, which overrides a `timeout` set in your own `cucumber.js`, so raise it here instead. |
225
228
  | `WEBSHIP_REPORT_DISABLE` | Set to `1` to skip auto-generating the HTML report on cucumber-js process exit. |
226
229
  | `WEBSHIP_REPORT_ARGS` | Extra CLI flags forwarded to `bin/generate-reports.js`. e.g. `--theme hierarchy --layout 2`. |
227
230
 
File without changes
File without changes
File without changes
File without changes
@@ -22,6 +22,12 @@ The following step variations are available:
22
22
  - Then I should see "value" in the "text" element by attr
23
23
  - Then I should not see "value" in the "text" element by attr
24
24
 
25
+ ## Seeing an element
26
+
27
+ `I should see (a/an) "text" element` and `I should not see (a/an) "text" element` name the element by its exact visible text, as it reads on the page. A `<label for="...">` stands for the control it labels. "Should not see" is the opposite of "should see": it passes when no element named that way is visible, so an element that is hidden does not fail it.
28
+
29
+ The text is not a CSS selector. For a selector use `"<selector>" should be visible` or `"<selector>" should not be visible`.
30
+
25
31
  ## Purpose
26
32
 
27
33
  "This step is useful for verifying that certain elements or messages are displayed correctly on a webpage or application, ensuring that the expected content is visible to the user or the automated tests."
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
@@ -26,6 +26,14 @@
26
26
  <button type="submit">Submit</button>
27
27
  </form>
28
28
  </main>
29
+ <!-- Hidden from assistive technology: a closed overlay. Nothing in here is
30
+ reachable, so no accessibility probe should report it. -->
31
+ <div class="scrim" aria-hidden="true" style="display:none">
32
+ <button type="button" tabindex="-1"></button>
33
+ <a href="/closed"></a>
34
+ <img src="data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==">
35
+ <input type="text" name="scrim-field">
36
+ </div>
29
37
  <footer><small>&copy; 2026</small></footer>
30
38
  </body>
31
39
  </html>
File without changes
File without changes
File without changes
File without changes
File without changes
@@ -0,0 +1,17 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Element visibility</title>
6
+ </head>
7
+ <body>
8
+ <h1>Account</h1>
9
+
10
+ <p><label for="email">Email</label> <input id="email" type="text"></p>
11
+ <p><input id="save" type="button" value="Save"></p>
12
+ <p id="note" style="display: none">Hidden note</p>
13
+ <p><label for="ghost">Ghost label</label><input id="ghost" type="text" style="display: none"></p>
14
+
15
+ <script>var promo = 'Promo banner';</script>
16
+ </body>
17
+ </html>
File without changes
File without changes
File without changes
File without changes
File without changes
@@ -0,0 +1,22 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Native dialogs</title>
6
+ </head>
7
+ <body>
8
+ <h1>Native dialogs</h1>
9
+
10
+ <p><button id="delete" type="button">Delete item</button></p>
11
+ <p id="result">Waiting</p>
12
+
13
+ <script>
14
+ var clicks = 0;
15
+ document.getElementById('delete').addEventListener('click', function () {
16
+ clicks += 1;
17
+ var answer = window.confirm('Delete this item?') ? 'Item deleted' : 'Deletion cancelled';
18
+ document.getElementById('result').textContent = answer + ' #' + clicks;
19
+ });
20
+ </script>
21
+ </body>
22
+ </html>
@@ -0,0 +1,32 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Never Settles</title>
6
+ </head>
7
+ <body>
8
+ <h1 id="page-title">Never Settles</h1>
9
+
10
+ <p id="intro">
11
+ This fixture never reaches network idle and never drains its timers, the way a
12
+ production page with analytics, a chat widget or a carousel behaves.
13
+ </p>
14
+
15
+ <p>Beat: <span id="beat">0</span></p>
16
+
17
+ <script>
18
+ // A request every 120ms: Playwright's "networkidle" needs 500ms with no
19
+ // in-flight network, so this page never reaches it.
20
+ // A self-rescheduling setTimeout: window.__webshipPendingTimers can
21
+ // therefore never fall back to 0 either.
22
+ var beat = 0;
23
+ function tick() {
24
+ beat++;
25
+ document.getElementById('beat').textContent = String(beat);
26
+ fetch('example-api.json?beat=' + beat, { cache: 'no-store' }).catch(function () {});
27
+ setTimeout(tick, 120);
28
+ }
29
+ setTimeout(tick, 120);
30
+ </script>
31
+ </body>
32
+ </html>
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
@@ -0,0 +1,18 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>Web-first text</title>
6
+ </head>
7
+ <body>
8
+ <h1>Home</h1>
9
+
10
+ <footer class="site-footer">
11
+ <p>Powered by
12
+ Example</p>
13
+ </footer>
14
+
15
+ <p class="price">Price:&nbsp;&nbsp;$99</p>
16
+ <p class="tagline"> Built with care </p>
17
+ </body>
18
+ </html>