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 +1 -1
- package/CLAUDE.md +5 -5
- package/bin/init-webship.js +1 -1
- package/cucumber.js +3 -1
- package/docs/02-bbr-smart-waits.md +24 -1
- package/docs/04-step-reference.md +4 -0
- package/docs/10-accessibility.md +24 -3
- package/docs/README.md +2 -2
- package/docs/global-settings.md +1 -0
- package/examples/a11y.html +8 -0
- package/examples/never-settles.html +32 -0
- package/package.json +1 -1
- package/tests/features/a11y.feature +22 -0
- package/tests/features/smart-settle-budget.feature +12 -0
- package/tests/step-definitions/a11y.steps.js +339 -113
- package/tests/step-definitions/webship.js +57 -20
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/` —
|
|
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
|
-
|
|
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 (
|
|
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/ #
|
|
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`
|
package/bin/init-webship.js
CHANGED
|
@@ -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.
|
|
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
|
|
package/docs/10-accessibility.md
CHANGED
|
@@ -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)
|
|
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
|
|
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
|
-
**
|
|
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 (
|
|
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
|
package/docs/global-settings.md
CHANGED
|
@@ -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
|
|
package/examples/a11y.html
CHANGED
|
@@ -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>© 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
|
@@ -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
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
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
|
-
|
|
89
|
-
|
|
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
|
-
|
|
125
|
-
|
|
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
|
|
161
|
-
assert.ok(
|
|
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
|
|
181
|
-
assert.ok(
|
|
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
|
|
203
|
-
assert.
|
|
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
|
|
296
|
-
assert.ok(
|
|
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
|
-
|
|
337
|
-
|
|
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
|
-
|
|
410
|
-
|
|
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
|
-
|
|
439
|
-
|
|
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
|
-
|
|
474
|
-
|
|
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
|
-
|
|
502
|
-
|
|
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
|
|
619
|
-
assert.ok(
|
|
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
|
|
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
|
|
642
|
-
|
|
643
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
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) {
|