webship-js 2.0.5 → 2.0.6

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 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/ # 72 .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`
@@ -10,7 +10,7 @@ const packagePath = path.join(__dirname, '..');
10
10
 
11
11
  const CUCUMBER_JS = `module.exports = {
12
12
  default: {
13
- timeout: 30000,
13
+ timeout: 30000, // Overridden by webship-js's setDefaultTimeout (45s); raise it with WEBSHIP_STEP_TIMEOUT.
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).
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
@@ -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
 
@@ -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
 
@@ -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"`.
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
@@ -222,6 +222,7 @@ const config = {
222
222
  | Env var | Effect |
223
223
  | --- | --- |
224
224
  | `WEBSHIP_AUTO_SETTLE` | Set to `off` to disable the BBR auto-settle hook (`smartSettle(page, 1500)` after every state-changing step). |
225
+ | `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
226
  | `WEBSHIP_REPORT_DISABLE` | Set to `1` to skip auto-generating the HTML report on cucumber-js process exit. |
226
227
  | `WEBSHIP_REPORT_ARGS` | Extra CLI flags forwarded to `bin/generate-reports.js`. e.g. `--theme hierarchy --layout 2`. |
227
228
 
@@ -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>
@@ -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>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webship-js",
3
- "version": "2.0.5",
3
+ "version": "2.0.6",
4
4
  "description": "Webship JS automated functional testing.",
5
5
  "main": "index.js",
6
6
  "bin": {
@@ -37,3 +37,25 @@ Feature: Accessibility (a11y) smoke checks
37
37
  And the page should not violate the accessibility rule "image-alt"
38
38
  And the page should not violate the accessibility rule "label"
39
39
  And the page should pass the accessibility rules "image-alt, label, button-name"
40
+
41
+ Scenario: Elements hidden from assistive technology are out of scope
42
+ Given I am on "/a11y.html"
43
+ Then every button should have an accessible name
44
+ And every link should have an accessible name
45
+ And every image should have an alt attribute
46
+ And every form field should have an accessible label
47
+
48
+ Scenario: The impact gate covers everything worse than the level named
49
+ Given I am on "/a11y.html"
50
+ Then the page should have no minor accessibility violations
51
+ And the page should have no moderate accessibility violations
52
+ And the page should have no serious accessibility violations
53
+ And the page should have no critical accessibility violations
54
+ And the page should have no accessibility violations
55
+
56
+ Scenario: One step for the whole page
57
+ Given I am on "/a11y.html"
58
+ Then the page should pass the full accessibility check
59
+ And the page should pass the full accessibility check at level "AA"
60
+ And the element "main" should not violate the accessibility rule "image-alt"
61
+ And I print the full accessibility check
@@ -0,0 +1,12 @@
1
+ Feature: Smart wait stays inside its budget
2
+
3
+ A page with analytics, a chat widget or a self-rescheduling timer never
4
+ reaches network idle and never drains its pending timers. The smart wait has
5
+ to spend its budget and hand control back, rather than block until cucumber
6
+ kills the step.
7
+
8
+ Scenario: A page that never settles does not stall the run
9
+ Given I am on "/never-settles.html"
10
+ Then I should see "Never Settles"
11
+ When I wait until the page is loaded
12
+ Then I should see "Never Settles"
@@ -42,6 +42,23 @@ const WCAG_TAGS = {
42
42
  'AAA': ['wcag2a', 'wcag2aa', 'wcag2aaa', 'wcag21a', 'wcag21aa', 'wcag21aaa', 'wcag22aaa'],
43
43
  };
44
44
 
45
+ // Impact is a severity ladder, not a set of unrelated labels. A gate named
46
+ // for one level covers that level and everything worse than it, so a page
47
+ // asked for no serious violations can never pass while a critical one stands.
48
+ const IMPACT_ORDER = ['minor', 'moderate', 'serious', 'critical'];
49
+
50
+ // axe leaves `impact` null on a few rules. Rank those at the bottom of the
51
+ // ladder so they are still reported by the widest gate instead of vanishing.
52
+ function impactRank(violation) {
53
+ const i = IMPACT_ORDER.indexOf(violation.impact);
54
+ return i === -1 ? 0 : i;
55
+ }
56
+
57
+ function atOrAbove(violations, impact) {
58
+ const floor = IMPACT_ORDER.indexOf(impact);
59
+ return violations.filter((v) => impactRank(v) >= floor);
60
+ }
61
+
45
62
  function summariseViolations(violations) {
46
63
  if (violations.length === 0) return 'no violations';
47
64
  const head = violations.slice(0, 5).map((v) =>
@@ -62,6 +79,152 @@ async function runAxe(world, opts = {}) {
62
79
  return builder.analyze();
63
80
  }
64
81
 
82
+ // ---------------------------------------------------------------------------
83
+ // The structural audit
84
+ // ---------------------------------------------------------------------------
85
+ //
86
+ // One page-side pass gathers every structural finding at once, and every
87
+ // structural step below reads its own slice out of it. One implementation,
88
+ // many gates, so a probe and the whole-page check can never disagree.
89
+ //
90
+ // Anything hidden from assistive technology is out of scope. A control behind
91
+ // `aria-hidden`, `inert`, `hidden`, `display: none` or `visibility: hidden` is
92
+ // not reachable, so a missing name on it is not a barrier. axe takes the same
93
+ // view, and a suite that did not was failing on scrims and closed menus.
94
+
95
+ const STRUCTURE = {
96
+ imageAlt: 'image(s) without an alt attribute',
97
+ buttonName: 'button(s) without an accessible name',
98
+ linkName: 'link(s) without an accessible name',
99
+ fieldLabel: 'unlabeled form field(s)',
100
+ frameTitle: 'iframe(s) without a title',
101
+ positiveTabindex: 'element(s) with a positive tabindex',
102
+ ariaReference: 'broken ARIA reference(s)',
103
+ oneH1: 'not exactly one h1',
104
+ headingOrder: 'skipped heading level(s)',
105
+ emptyHeading: 'empty heading(s)',
106
+ mainLandmark: 'no main landmark',
107
+ navLandmark: 'no navigation landmark',
108
+ htmlLang: 'no language on <html>',
109
+ pageTitle: 'no page title',
110
+ zoomAllowed: 'zoom blocked',
111
+ uniqueNavName: 'navigation landmark(s) sharing one name',
112
+ };
113
+
114
+ async function structuralAudit(page) {
115
+ return page.evaluate(() => {
116
+ const atHidden = (el) => {
117
+ if (el.closest('[aria-hidden="true"], [inert], [hidden]')) return true;
118
+ const s = getComputedStyle(el);
119
+ return s.display === 'none' || s.visibility === 'hidden';
120
+ };
121
+ const visible = (sel) => Array.from(document.querySelectorAll(sel)).filter((el) => !atHidden(el));
122
+ const attr = (el, name) => (el.getAttribute(name) || '').trim();
123
+ // The accessible name an assistive technology would announce, in the order
124
+ // HTML gives them. Enough for a "has a name at all" gate, which is what
125
+ // these probes are.
126
+ const named = (el) => {
127
+ if (attr(el, 'aria-label')) return true;
128
+ if (el.hasAttribute('aria-labelledby')) return true;
129
+ if (attr(el, 'title')) return true;
130
+ if (el.tagName === 'INPUT') return Boolean((el.value || '').trim());
131
+ if ((el.textContent || '').trim()) return true;
132
+ const img = el.querySelector('img[alt]');
133
+ return Boolean(img && attr(img, 'alt'));
134
+ };
135
+ const brief = (el) => el.outerHTML.slice(0, 120);
136
+ const found = {};
137
+ const add = (key, items) => { if (items.length) found[key] = items; };
138
+
139
+ add('imageAlt', visible('img').filter((img) => {
140
+ if (img.hasAttribute('alt')) return false;
141
+ const role = img.getAttribute('role');
142
+ if (role === 'presentation' || role === 'none') return false;
143
+ return !(attr(img, 'aria-label') || img.hasAttribute('aria-labelledby') || attr(img, 'title'));
144
+ }).map(brief));
145
+
146
+ add('buttonName', visible('button, [role="button"], input[type="submit"], input[type="button"]')
147
+ .filter((el) => !named(el)).map(brief));
148
+
149
+ add('linkName', visible('a[href]').filter((el) => !named(el)).map(brief));
150
+
151
+ add('fieldLabel', visible('input:not([type="hidden"]), select, textarea').filter((el) => {
152
+ const type = el.getAttribute('type');
153
+ if (type === 'submit' || type === 'button' || type === 'reset' || type === 'image') return false;
154
+ if (attr(el, 'aria-label') || el.hasAttribute('aria-labelledby') || attr(el, 'title')) return false;
155
+ if (el.id && document.querySelector(`label[for="${CSS.escape(el.id)}"]`)) return false;
156
+ return !el.closest('label');
157
+ }).map(brief));
158
+
159
+ add('frameTitle', visible('iframe')
160
+ .filter((el) => !attr(el, 'title') && !attr(el, 'aria-label')).map(brief));
161
+
162
+ add('positiveTabindex', Array.from(document.querySelectorAll('[tabindex]'))
163
+ .filter((el) => parseInt(el.getAttribute('tabindex'), 10) > 0).map(brief));
164
+
165
+ const refAttrs = ['aria-labelledby', 'aria-describedby', 'aria-controls', 'aria-owns', 'aria-flowto'];
166
+ const broken = [];
167
+ for (const name of refAttrs) {
168
+ for (const el of Array.from(document.querySelectorAll(`[${name}]`))) {
169
+ for (const id of (el.getAttribute(name) || '').split(/\s+/).filter(Boolean)) {
170
+ if (!document.getElementById(id)) {
171
+ broken.push(`<${el.tagName.toLowerCase()} ${name}="${el.getAttribute(name)}"> references a missing id "${id}"`);
172
+ }
173
+ }
174
+ }
175
+ }
176
+ add('ariaReference', broken);
177
+
178
+ const headings = visible('h1, h2, h3, h4, h5, h6');
179
+ const h1s = headings.filter((h) => h.tagName === 'H1');
180
+ if (h1s.length !== 1) add('oneH1', [`found ${h1s.length}`]);
181
+
182
+ const skips = [];
183
+ let previous = 0;
184
+ for (const h of headings) {
185
+ const level = parseInt(h.tagName.slice(1), 10);
186
+ if (previous > 0 && level - previous > 1) {
187
+ skips.push(`h${previous} to h${level} at "${(h.textContent || '').trim().slice(0, 40)}"`);
188
+ }
189
+ previous = level;
190
+ }
191
+ add('headingOrder', skips);
192
+
193
+ add('emptyHeading', headings.filter((h) => !(h.textContent || '').trim() && !named(h)).map(brief));
194
+
195
+ if (!visible('main, [role="main"]').length) add('mainLandmark', ['none on the page']);
196
+ if (!visible('nav, [role="navigation"]').length) add('navLandmark', ['none on the page']);
197
+ if (!attr(document.documentElement, 'lang')) add('htmlLang', ['none set']);
198
+ if (!(document.title || '').trim()) add('pageTitle', ['empty']);
199
+
200
+ const meta = document.querySelector('meta[name="viewport"]');
201
+ if (meta) {
202
+ const content = (meta.getAttribute('content') || '').toLowerCase();
203
+ // Read the scale as a number. Any maximum-scale below 2 caps zoom, the
204
+ // same line axe draws, and a regex written for "1" missed 0.5 and 1.5.
205
+ const scale = /maximum-scale\s*=\s*([0-9.]+)/.exec(content);
206
+ const blocked = /user-scalable\s*=\s*(no|0)\b/.test(content)
207
+ || (scale && parseFloat(scale[1]) < 2);
208
+ if (blocked) add('zoomAllowed', [`<meta name="viewport" content="${content}">`]);
209
+ }
210
+
211
+ const navNames = visible('nav, [role="navigation"]').map((el) => attr(el, 'aria-label').toLowerCase());
212
+ const shared = navNames.filter((name, i) => name && navNames.indexOf(name) !== i);
213
+ add('uniqueNavName', Array.from(new Set(shared)));
214
+
215
+ return found;
216
+ });
217
+ }
218
+
219
+ // Assert one slice of the structural audit, in the wording that slice's own
220
+ // step has always used.
221
+ async function assertStructure(page, key, message) {
222
+ const found = await structuralAudit(page);
223
+ const items = found[key] || [];
224
+ assert.strictEqual(items.length, 0,
225
+ `${message(items)}\n ${items.slice(0, 20).join('\n ')}`);
226
+ }
227
+
65
228
  // ---------------------------------------------------------------------------
66
229
  // Image alt text
67
230
  // ---------------------------------------------------------------------------
@@ -69,10 +232,12 @@ async function runAxe(world, opts = {}) {
69
232
  /**
70
233
  * Assert every <img> on the page has an `alt` attribute.
71
234
  *
72
- * Empty `alt=""` is allowed (decorative images per WCAG); `role="presentation"`
73
- * is also allowed. Only a missing `alt` attribute fails. Iterates every <img>
74
- * in the document, including those nested in shadow-light DOM that the page
75
- * has rendered, so it works on infinite-scroll lists and image galleries too.
235
+ * Empty `alt=""` is allowed (decorative images per WCAG); `role="presentation"`,
236
+ * `role="none"`, `aria-label`, `aria-labelledby` and `title` are also accepted.
237
+ * Only a missing `alt` attribute fails. Images hidden from assistive technology
238
+ * (`aria-hidden`, `inert`, `hidden`, `display: none`, `visibility: hidden`)
239
+ * are skipped, the same as axe skips them. The same rule applies to the button,
240
+ * link and form field probes.
76
241
  *
77
242
  * Example #1: Then every image should have an alt attribute
78
243
  * Example #2: And every image should have an alt attribute
@@ -85,13 +250,8 @@ async function runAxe(world, opts = {}) {
85
250
  *
86
251
  */
87
252
  Then(/^every image should have an alt attribute$/, async function () {
88
- const missing = await this.page.evaluate(() =>
89
- Array.from(document.querySelectorAll('img'))
90
- .filter((img) => !img.hasAttribute('alt') && img.getAttribute('role') !== 'presentation')
91
- .map((img) => img.outerHTML.slice(0, 120))
92
- );
93
- assert.strictEqual(missing.length, 0,
94
- `Found ${missing.length} <img> without alt:\n ${missing.join('\n ')}`);
253
+ await assertStructure(this.page, 'imageAlt',
254
+ (items) => `Found ${items.length} <img> without alt:`);
95
255
  });
96
256
 
97
257
  // ---------------------------------------------------------------------------
@@ -121,19 +281,8 @@ Then(/^every image should have an alt attribute$/, async function () {
121
281
  *
122
282
  */
123
283
  Then(/^every form field should have an accessible label$/, async function () {
124
- const missing = await this.page.evaluate(() => {
125
- const fields = Array.from(document.querySelectorAll('input:not([type="hidden"]), select, textarea'));
126
- return fields.filter((el) => {
127
- if (el.hasAttribute('aria-label') || el.hasAttribute('aria-labelledby')) return false;
128
- if (el.id && document.querySelector(`label[for="${el.id}"]`)) return false;
129
- if (el.closest('label')) return false;
130
- const t = el.getAttribute('type');
131
- if (t === 'submit' || t === 'button' || t === 'reset' || t === 'image') return false;
132
- return true;
133
- }).map((el) => el.outerHTML.slice(0, 120));
134
- });
135
- assert.strictEqual(missing.length, 0,
136
- `Found ${missing.length} unlabeled form field(s):\n ${missing.join('\n ')}`);
284
+ await assertStructure(this.page, 'fieldLabel',
285
+ (items) => `Found ${items.length} unlabeled form field(s):`);
137
286
  });
138
287
 
139
288
  // ---------------------------------------------------------------------------
@@ -157,8 +306,8 @@ Then(/^every form field should have an accessible label$/, async function () {
157
306
  *
158
307
  */
159
308
  Then(/^the page should have a main landmark$/, async function () {
160
- const count = await this.page.locator('main, [role="main"]').count();
161
- assert.ok(count >= 1, 'Page is missing a <main> or [role="main"] landmark.');
309
+ const found = await structuralAudit(this.page);
310
+ assert.ok(!found.mainLandmark, 'Page is missing a <main> or [role="main"] landmark.');
162
311
  });
163
312
 
164
313
  /**
@@ -177,8 +326,8 @@ Then(/^the page should have a main landmark$/, async function () {
177
326
  *
178
327
  */
179
328
  Then(/^the page should have a navigation landmark$/, async function () {
180
- const count = await this.page.locator('nav, [role="navigation"]').count();
181
- assert.ok(count >= 1, 'Page is missing a <nav> or [role="navigation"] landmark.');
329
+ const found = await structuralAudit(this.page);
330
+ assert.ok(!found.navLandmark, 'Page is missing a <nav> or [role="navigation"] landmark.');
182
331
  });
183
332
 
184
333
  /**
@@ -199,8 +348,8 @@ Then(/^the page should have a navigation landmark$/, async function () {
199
348
  *
200
349
  */
201
350
  Then(/^the page should have exactly one h1$/, async function () {
202
- const count = await this.page.locator('h1').count();
203
- assert.strictEqual(count, 1, `Expected 1 <h1>, found ${count}.`);
351
+ const found = await structuralAudit(this.page);
352
+ assert.ok(!found.oneH1, `Expected 1 <h1>, ${(found.oneH1 || [''])[0]}.`);
204
353
  });
205
354
 
206
355
  // ---------------------------------------------------------------------------
@@ -292,8 +441,8 @@ Then(/^the focused element should be labeled "([^"]*)"$/, async function (text)
292
441
  *
293
442
  */
294
443
  Then(/^the page should declare a language$/, async function () {
295
- const lang = await this.page.evaluate(() => document.documentElement.getAttribute('lang') || '');
296
- assert.ok(lang.length > 0, 'Page <html> is missing a "lang" attribute.');
444
+ const found = await structuralAudit(this.page);
445
+ assert.ok(!found.htmlLang, 'Page <html> is missing a "lang" attribute.');
297
446
  });
298
447
 
299
448
  /**
@@ -333,21 +482,8 @@ Then(/^the page language should be "([^"]*)"$/, async function (expected) {
333
482
  *
334
483
  */
335
484
  Then(/^the heading hierarchy should be valid$/, async function () {
336
- const skips = await this.page.evaluate(() => {
337
- const out = [];
338
- const headings = Array.from(document.querySelectorAll('h1, h2, h3, h4, h5, h6'));
339
- let prev = 0;
340
- for (const h of headings) {
341
- const level = parseInt(h.tagName.slice(1), 10);
342
- if (prev > 0 && level - prev > 1) {
343
- out.push(`<${h.tagName.toLowerCase()}>${(h.textContent || '').slice(0, 60).trim()}</${h.tagName.toLowerCase()}> (skipped from h${prev})`);
344
- }
345
- prev = level;
346
- }
347
- return out;
348
- });
349
- assert.strictEqual(skips.length, 0,
350
- `Heading hierarchy skips levels:\n ${skips.join('\n ')}`);
485
+ await assertStructure(this.page, 'headingOrder',
486
+ (items) => `Heading hierarchy skips ${items.length} level(s):`);
351
487
  });
352
488
 
353
489
  // ---------------------------------------------------------------------------
@@ -406,19 +542,8 @@ Then(/^the page should have a skip link$/, async function () {
406
542
  *
407
543
  */
408
544
  Then(/^every button should have an accessible name$/, async function () {
409
- const missing = await this.page.evaluate(() => {
410
- const els = Array.from(document.querySelectorAll('button, [role="button"], input[type="submit"], input[type="button"]'));
411
- return els.filter((el) => {
412
- if (el.hasAttribute('aria-label') && el.getAttribute('aria-label').trim()) return false;
413
- if (el.hasAttribute('aria-labelledby')) return false;
414
- if (el.tagName === 'INPUT') {
415
- return !((el.value || '').trim());
416
- }
417
- return !(el.textContent || '').trim();
418
- }).map((el) => el.outerHTML.slice(0, 120));
419
- });
420
- assert.strictEqual(missing.length, 0,
421
- `Found ${missing.length} button(s) without accessible name:\n ${missing.join('\n ')}`);
545
+ await assertStructure(this.page, 'buttonName',
546
+ (items) => `Found ${items.length} button(s) without accessible name:`);
422
547
  });
423
548
 
424
549
  /**
@@ -435,20 +560,8 @@ Then(/^every button should have an accessible name$/, async function () {
435
560
  *
436
561
  */
437
562
  Then(/^every link should have an accessible name$/, async function () {
438
- const missing = await this.page.evaluate(() => {
439
- const links = Array.from(document.querySelectorAll('a[href]'));
440
- return links.filter((a) => {
441
- if (a.hasAttribute('aria-label') && a.getAttribute('aria-label').trim()) return false;
442
- if (a.hasAttribute('aria-labelledby')) return false;
443
- if ((a.textContent || '').trim()) return false;
444
- // Allow image-link if alt has text.
445
- const img = a.querySelector('img[alt]');
446
- if (img && (img.getAttribute('alt') || '').trim()) return false;
447
- return true;
448
- }).map((a) => a.outerHTML.slice(0, 120));
449
- });
450
- assert.strictEqual(missing.length, 0,
451
- `Found ${missing.length} link(s) without accessible name:\n ${missing.join('\n ')}`);
563
+ await assertStructure(this.page, 'linkName',
564
+ (items) => `Found ${items.length} link(s) without accessible name:`);
452
565
  });
453
566
 
454
567
  // ---------------------------------------------------------------------------
@@ -470,13 +583,8 @@ Then(/^every link should have an accessible name$/, async function () {
470
583
  *
471
584
  */
472
585
  Then(/^no element should have a positive tabindex$/, async function () {
473
- const offenders = await this.page.evaluate(() =>
474
- Array.from(document.querySelectorAll('[tabindex]'))
475
- .filter((el) => parseInt(el.getAttribute('tabindex'), 10) > 0)
476
- .map((el) => el.outerHTML.slice(0, 120))
477
- );
478
- assert.strictEqual(offenders.length, 0,
479
- `Found ${offenders.length} element(s) with positive tabindex:\n ${offenders.join('\n ')}`);
586
+ await assertStructure(this.page, 'positiveTabindex',
587
+ (items) => `Found ${items.length} element(s) with positive tabindex:`);
480
588
  });
481
589
 
482
590
  // ---------------------------------------------------------------------------
@@ -498,24 +606,8 @@ Then(/^no element should have a positive tabindex$/, async function () {
498
606
  *
499
607
  */
500
608
  Then(/^every ARIA reference should resolve$/, async function () {
501
- const broken = await this.page.evaluate(() => {
502
- const attrs = ['aria-labelledby', 'aria-describedby', 'aria-controls', 'aria-owns', 'aria-flowto'];
503
- const out = [];
504
- for (const attr of attrs) {
505
- const els = Array.from(document.querySelectorAll(`[${attr}]`));
506
- for (const el of els) {
507
- const ids = (el.getAttribute(attr) || '').split(/\s+/).filter(Boolean);
508
- for (const id of ids) {
509
- if (!document.getElementById(id)) {
510
- out.push(`<${el.tagName.toLowerCase()} ${attr}="${el.getAttribute(attr)}"> — missing id "${id}"`);
511
- }
512
- }
513
- }
514
- }
515
- return out;
516
- });
517
- assert.strictEqual(broken.length, 0,
518
- `Found ${broken.length} broken ARIA reference(s):\n ${broken.join('\n ')}`);
609
+ await assertStructure(this.page, 'ariaReference',
610
+ (items) => `Found ${items.length} broken ARIA reference(s):`);
519
611
  });
520
612
 
521
613
  /**
@@ -615,8 +707,8 @@ Then(/^required fields should be consistently marked$/, async function () {
615
707
  *
616
708
  */
617
709
  Then(/^the page should have a title$/, async function () {
618
- const title = await this.page.title();
619
- assert.ok(title && title.trim().length > 0, 'Page is missing a non-empty <title>.');
710
+ const found = await structuralAudit(this.page);
711
+ assert.ok(!found.pageTitle, 'Page is missing a non-empty <title>.');
620
712
  });
621
713
 
622
714
  // ---------------------------------------------------------------------------
@@ -625,7 +717,7 @@ Then(/^the page should have a title$/, async function () {
625
717
 
626
718
  /**
627
719
  * Assert the viewport meta tag does not disable user-scaling
628
- * (`user-scalable=no` or `maximum-scale=1`). WCAG 1.4.4 / 1.4.10.
720
+ * (`user-scalable=no`, or a `maximum-scale` below 2). WCAG 1.4.4 / 1.4.10.
629
721
  *
630
722
  * Example #1: Then user zoom should be allowed
631
723
  * Example #2: Given I am on the homepage
@@ -638,13 +730,9 @@ Then(/^the page should have a title$/, async function () {
638
730
  *
639
731
  */
640
732
  Then(/^user zoom should be allowed$/, async function () {
641
- const blocked = await this.page.evaluate(() => {
642
- const m = document.querySelector('meta[name="viewport"]');
643
- if (!m) return false;
644
- const c = (m.getAttribute('content') || '').toLowerCase();
645
- return /user-scalable\s*=\s*(no|0)/.test(c) || /maximum-scale\s*=\s*1(\.0)?(\b|$)/.test(c);
646
- });
647
- assert.ok(!blocked, 'Viewport meta tag disables user-scaling — fails WCAG 1.4.4 / 1.4.10.');
733
+ const found = await structuralAudit(this.page);
734
+ assert.ok(!found.zoomAllowed,
735
+ `Viewport meta tag disables user-scaling: ${(found.zoomAllowed || [''])[0]}`);
648
736
  });
649
737
 
650
738
  // ===========================================================================
@@ -671,8 +759,9 @@ Then(/^the page should pass an accessibility audit(?: at level "(A|AA|AAA)")?$/,
671
759
  });
672
760
 
673
761
  /**
674
- * Assert NO axe violations of the given impact severity.
675
- * Levels: `minor`, `moderate`, `serious`, `critical`.
762
+ * Assert NO axe violations at the given impact or worse.
763
+ * Levels, lowest first: `minor`, `moderate`, `serious`, `critical`.
764
+ * `serious` also fails on a critical violation, and `minor` on any violation.
676
765
  *
677
766
  * Use to gate merges on critical/serious issues while triaging minor regressions.
678
767
  *
@@ -687,9 +776,48 @@ Then(/^the page should pass an accessibility audit(?: at level "(A|AA|AAA)")?$/,
687
776
  */
688
777
  Then(/^the page should have no (critical|serious|moderate|minor) accessibility violations$/, async function (impact) {
689
778
  const result = await runAxe(this);
690
- const filtered = result.violations.filter((v) => v.impact === impact);
779
+ const filtered = atOrAbove(result.violations, impact);
691
780
  assert.strictEqual(filtered.length, 0,
692
- `Expected no ${impact} violations, got ${filtered.length}:\n${summariseViolations(filtered)}`);
781
+ `Expected no ${impact} or worse violations, got ${filtered.length}:\n${summariseViolations(filtered)}`);
782
+ });
783
+
784
+ /**
785
+ * Assert axe finds no violations at all, whatever their impact.
786
+ *
787
+ * Example #1: Then the page should have no accessibility violations
788
+ * Example #2: Given I am on the homepage
789
+ * Then the page should have no accessibility violations
790
+ * Example #3: When I follow "Pricing"
791
+ * Then the page should have no accessibility violations
792
+ * Example #4: And the page should have no accessibility violations
793
+ * Example #5: Then the page should have no accessibility violations
794
+ * And the heading hierarchy should be valid
795
+ *
796
+ */
797
+ Then(/^the page should have no accessibility violations$/, async function () {
798
+ const result = await runAxe(this);
799
+ assert.strictEqual(result.violations.length, 0,
800
+ `Expected no violations, got ${result.violations.length}:\n${summariseViolations(result.violations)}`);
801
+ });
802
+
803
+ /**
804
+ * Assert a specific axe rule does not fire inside one subtree. Use when a
805
+ * rule is clean in your own component but not yet across the whole page.
806
+ *
807
+ * Example #1: Then the element "main" should not violate the accessibility rule "color-contrast"
808
+ * Example #2: Then the element "#checkout" should not violate the accessibility rule "label"
809
+ * Example #3: And the element ".card" should not violate the accessibility rule "heading-order"
810
+ * Example #4: Then the element "footer" should not violate the accessibility rule "link-name"
811
+ * Example #5: Then the element "[data-testid=nav]" should not violate the accessibility rule "landmark-unique"
812
+ *
813
+ */
814
+ Then(/^the element "([^"]*)" should not violate the accessibility rule "([^"]*)"$/, async function (selector, ruleId) {
815
+ const result = await runAxe(this, { include: selector });
816
+ const hit = result.violations.find((v) => v.id === ruleId);
817
+ if (hit) {
818
+ assert.fail(`Rule "${ruleId}" violated inside "${selector}" by ${hit.nodes.length} node(s):\n `
819
+ + hit.nodes.slice(0, 5).map((n) => n.target.join(' ')).join('\n '));
820
+ }
693
821
  });
694
822
 
695
823
  /**
@@ -798,3 +926,101 @@ Then(/^the page should pass the accessibility rules "([^"]*)"$/, async function
798
926
  assert.strictEqual(hits.length, 0,
799
927
  `Required rule(s) violated:\n${summariseViolations(hits)}`);
800
928
  });
929
+
930
+ // ---------------------------------------------------------------------------
931
+ // The full check
932
+ // ---------------------------------------------------------------------------
933
+
934
+ // axe already reports these, so the structural pass keeps quiet about anything
935
+ // axe has just named. One finding, one line, whichever engine found it.
936
+ const AXE_COVERS = {
937
+ 'image-alt': 'imageAlt',
938
+ 'button-name': 'buttonName',
939
+ 'input-button-name': 'buttonName',
940
+ 'link-name': 'linkName',
941
+ 'label': 'fieldLabel',
942
+ 'select-name': 'fieldLabel',
943
+ 'form-field-multiple-labels': 'fieldLabel',
944
+ 'frame-title': 'frameTitle',
945
+ 'tabindex': 'positiveTabindex',
946
+ 'aria-valid-attr-value': 'ariaReference',
947
+ 'page-has-heading-one': 'oneH1',
948
+ 'heading-order': 'headingOrder',
949
+ 'empty-heading': 'emptyHeading',
950
+ 'landmark-one-main': 'mainLandmark',
951
+ 'html-has-lang': 'htmlLang',
952
+ 'document-title': 'pageTitle',
953
+ 'meta-viewport': 'zoomAllowed',
954
+ 'meta-viewport-large': 'zoomAllowed',
955
+ 'landmark-unique': 'uniqueNavName',
956
+ };
957
+
958
+ // Facts about the page as a whole, reported as one line rather than a count.
959
+ const PAGE_FACTS = new Set(['oneH1', 'mainLandmark', 'navLandmark', 'htmlLang', 'pageTitle', 'zoomAllowed']);
960
+
961
+ function fullCheckReport(violations, found) {
962
+ const covered = new Set(violations.map((v) => AXE_COVERS[v.id]).filter(Boolean));
963
+ const lines = [];
964
+ if (violations.length) {
965
+ lines.push(`axe found ${violations.length} violation(s):\n${summariseViolations(violations)}`);
966
+ }
967
+ for (const [key, label] of Object.entries(STRUCTURE)) {
968
+ const items = found[key];
969
+ if (!items || covered.has(key)) continue;
970
+ if (PAGE_FACTS.has(key)) {
971
+ lines.push(`${label}: ${items[0]}`);
972
+ continue;
973
+ }
974
+ const head = `${items.length} ${label}`;
975
+ const shown = items.slice(0, 5);
976
+ const more = items.length > shown.length ? `\n ... and ${items.length - shown.length} more` : '';
977
+ lines.push(`${head}:\n ${shown.join('\n ')}${more}`);
978
+ }
979
+ return lines;
980
+ }
981
+
982
+ /**
983
+ * Run the whole accessibility check on the current page in one step: an axe
984
+ * audit at the given level (AA by default), plus every structural check in
985
+ * this file. A finding axe already named is not repeated. Reports every
986
+ * failure at once rather than stopping at the first.
987
+ *
988
+ * Example #1: Then the page should pass the full accessibility check
989
+ * Example #2: Then the page should pass the full accessibility check at level "AA"
990
+ * Example #3: And the page should pass the full accessibility check at level "A"
991
+ * Example #4: When I go to "/news"
992
+ * Then the page should pass the full accessibility check
993
+ * Example #5: Given I am an anonymous user
994
+ * When I am on the homepage
995
+ * Then the page should pass the full accessibility check at level "AA"
996
+ *
997
+ */
998
+ Then(/^the page should pass the full accessibility check(?: at level "(A|AA|AAA)")?$/, async function (level) {
999
+ const result = await runAxe(this, { tags: WCAG_TAGS[level || 'AA'] });
1000
+ const found = await structuralAudit(this.page);
1001
+ const lines = fullCheckReport(result.violations, found);
1002
+ assert.strictEqual(lines.length, 0,
1003
+ `The page failed ${lines.length} accessibility check(s):\n\n${lines.join('\n\n')}`);
1004
+ });
1005
+
1006
+ /**
1007
+ * The same whole-page check, reported rather than asserted. Use it to see
1008
+ * where a page stands before deciding what to gate on.
1009
+ *
1010
+ * Example #1: Then I print the full accessibility check
1011
+ * Example #2: When I go to "/about-us"
1012
+ * Then I print the full accessibility check
1013
+ * Example #3: And we print the full accessibility check
1014
+ * Example #4: Given I am an anonymous user
1015
+ * Then I print the full accessibility check
1016
+ * Example #5: Then I print the full accessibility check
1017
+ * And the page should have no critical accessibility violations
1018
+ *
1019
+ */
1020
+ Then(/^(?:I |we )*print the full accessibility check$/, async function () {
1021
+ const result = await runAxe(this, { tags: WCAG_TAGS.AA });
1022
+ const found = await structuralAudit(this.page);
1023
+ const lines = fullCheckReport(result.violations, found);
1024
+ console.log(`\n--- Full accessibility check: ${this.page.url()} ---`);
1025
+ console.log(lines.length ? lines.join('\n\n') : ' nothing to report');
1026
+ });
@@ -69,10 +69,27 @@ if (process.env.WEBSHIP_FILTER_HOOK_LINES !== 'off') {
69
69
  // late-firing setTimeout that mutates the DOM re-arms the wait correctly.
70
70
  // ---------------------------------------------------------------------------
71
71
 
72
+ /**
73
+ * Smallest timeout worth handing to Playwright. Playwright reads `timeout: 0`
74
+ * as "no timeout at all", so a spent budget must never reach it as a zero —
75
+ * that is how a settle could wait forever instead of giving up.
76
+ *
77
+ * @type {number}
78
+ */
79
+ const SETTLE_MIN_MS = 25;
80
+
72
81
  /**
73
82
  * Wait for the page to reach an "edge" of activity — DOM ready, network
74
83
  * idle, no pending AJAX or timers, and no DOM mutations for ≥250 ms.
75
84
  *
85
+ * Each stage gets a share of the budget rather than "whatever is left", so a
86
+ * stage that can never resolve cannot starve the ones after it. On a page with
87
+ * analytics, a chat widget or a self-rescheduling timer, `networkidle` never
88
+ * arrives; capping it at half the budget keeps the AJAX / pending-timer /
89
+ * DOM-quiet probe — the useful one — running.
90
+ *
91
+ * Returns within `timeout` ms even when nothing on the page ever settles.
92
+ *
76
93
  * @param {import('playwright').Page} page - Page being probed.
77
94
  * @param {number} [timeout=10000] - Total budget in ms.
78
95
  * @returns {Promise<void>}
@@ -80,26 +97,38 @@ if (process.env.WEBSHIP_FILTER_HOOK_LINES !== 'off') {
80
97
  async function smartSettle(page, timeout) {
81
98
  const total = typeof timeout === 'number' && timeout > 0 ? timeout : 10000;
82
99
  const deadline = Date.now() + total;
83
- const remaining = () => Math.max(0, deadline - Date.now());
84
100
 
85
- try { await page.waitForSelector('body', { state: 'attached', timeout: remaining() }); } catch { /* keep going */ }
86
- try { await page.waitForLoadState('domcontentloaded', { timeout: remaining() }); } catch { /* keep going */ }
87
- try { await page.waitForLoadState('networkidle', { timeout: remaining() }); } catch { /* keep going */ }
88
- try {
89
- await page.waitForFunction(
90
- (quietMs) => {
91
- const ajax = window.__webshipAjaxCount;
92
- const timers = window.__webshipPendingTimers;
93
- const last = window.__webshipLastMutation;
94
- if (typeof ajax === 'number' && ajax > 0) return false;
95
- if (typeof timers === 'number' && timers > 0) return false;
96
- if (typeof last === 'number' && Date.now() - last < quietMs) return false;
97
- return true;
98
- },
99
- 250,
100
- { timeout: remaining(), polling: 50 }
101
- );
102
- } catch { /* keep going */ }
101
+ // Milliseconds left in the budget. Never handed to Playwright directly: a
102
+ // zero there means "no timeout", not "return immediately".
103
+ const left = () => deadline - Date.now();
104
+
105
+ // Run one stage with at most `share` of the original budget, and never more
106
+ // than what is actually left. Returns false once the budget is spent, so the
107
+ // caller stops instead of calling Playwright with a useless timeout.
108
+ const stage = async (share, fn) => {
109
+ const remaining = left();
110
+ if (remaining < SETTLE_MIN_MS) return false;
111
+ const budget = Math.max(SETTLE_MIN_MS, Math.min(remaining, Math.round(total * share)));
112
+ try { await fn(budget); } catch { /* a stage timing out is not a failure */ }
113
+ return left() >= SETTLE_MIN_MS;
114
+ };
115
+
116
+ if (!await stage(0.25, (t) => page.waitForSelector('body', { state: 'attached', timeout: t }))) return;
117
+ if (!await stage(0.25, (t) => page.waitForLoadState('domcontentloaded', { timeout: t }))) return;
118
+ if (!await stage(0.5, (t) => page.waitForLoadState('networkidle', { timeout: t }))) return;
119
+ await stage(0.5, (t) => page.waitForFunction(
120
+ (quietMs) => {
121
+ const ajax = window.__webshipAjaxCount;
122
+ const timers = window.__webshipPendingTimers;
123
+ const last = window.__webshipLastMutation;
124
+ if (typeof ajax === 'number' && ajax > 0) return false;
125
+ if (typeof timers === 'number' && timers > 0) return false;
126
+ if (typeof last === 'number' && Date.now() - last < quietMs) return false;
127
+ return true;
128
+ },
129
+ 250,
130
+ { timeout: t, polling: 50 }
131
+ ));
103
132
  }
104
133
 
105
134
  /**
@@ -620,7 +649,15 @@ if (!global.__WEBSHIP_AUTO_REPORT__) {
620
649
  // (e.g. click() with no match) reach our try/catch wrappers BEFORE cucumber
621
650
  // trips its own timeout — otherwise testers see "function timed out" instead
622
651
  // of the friendly Why/Hint message.
623
- setDefaultTimeout(45 * 1000);
652
+ //
653
+ // setDefaultTimeout() runs at load time and overrides whatever `timeout` a
654
+ // consumer set in their own cucumber.js, so WEBSHIP_STEP_TIMEOUT is the
655
+ // way to raise (or lower) it from outside. 45s stays the default.
656
+ const STEP_TIMEOUT = (() => {
657
+ const raw = parseInt(process.env.WEBSHIP_STEP_TIMEOUT, 10);
658
+ return Number.isFinite(raw) && raw > 0 ? raw : 45 * 1000;
659
+ })();
660
+ setDefaultTimeout(STEP_TIMEOUT);
624
661
 
625
662
  class PlaywrightWorld extends World {
626
663
  constructor(options) {