webship-js 2.0.5 → 2.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (196) hide show
  1. package/.drone.yml +0 -0
  2. package/.harness/webship-js-pipeline.yml +0 -0
  3. package/.semaphore/semaphore.yml +0 -0
  4. package/.teamcity/pom.xml +0 -0
  5. package/.teamcity/settings.kts +0 -0
  6. package/.travis.yml +0 -0
  7. package/AGENTS.md +1 -1
  8. package/CLAUDE.md +5 -5
  9. package/Jenkinsfile +0 -0
  10. package/azure-pipelines.yml +0 -0
  11. package/bamboo-specs/bamboo.yml +0 -0
  12. package/bin/generate-reports.js +0 -0
  13. package/bin/init-webship.js +9 -10
  14. package/bin/postinstall.js +0 -0
  15. package/buildspec.yml +0 -0
  16. package/cloudbuild.yaml +0 -0
  17. package/codefresh.yml +0 -0
  18. package/cucumber.js +3 -1
  19. package/docs/00-quick-start.md +0 -0
  20. package/docs/01-getting-started.md +0 -0
  21. package/docs/02-bbr-smart-waits.md +24 -1
  22. package/docs/03-selector-registry.md +0 -0
  23. package/docs/04-step-reference.md +4 -0
  24. package/docs/05-web-first-assertions.md +2 -0
  25. package/docs/06-network-and-dialogs.md +0 -0
  26. package/docs/07-auth-state.md +0 -0
  27. package/docs/08-clock-mocking.md +0 -0
  28. package/docs/09-api-testing.md +0 -0
  29. package/docs/10-accessibility.md +24 -3
  30. package/docs/11-debugging.md +0 -0
  31. package/docs/12-ai-agent-guide.md +0 -0
  32. package/docs/13-faq.md +0 -0
  33. package/docs/14-recipes-cookbook.md +0 -0
  34. package/docs/15-tag-conventions.md +0 -0
  35. package/docs/16-ci-cd.md +0 -0
  36. package/docs/README.md +2 -2
  37. package/docs/advanced-screenshots/then-i-save-fullscreen-screenshot.md +0 -0
  38. package/docs/advanced-screenshots/then-i-save-width-x-height-screenshot.md +0 -0
  39. package/docs/advanced-screenshots/when-i-save-screenshot-name-filename.md +0 -0
  40. package/docs/advanced-screenshots.md +0 -0
  41. package/docs/advanced-selectors.md +0 -0
  42. package/docs/api-step-definitions.md +0 -0
  43. package/docs/global-settings.md +5 -2
  44. package/docs/install-webship-js/ddev-webship-js.md +0 -0
  45. package/docs/step-definitions/given-i-am-anonymous-user.md +0 -0
  46. package/docs/step-definitions/given-i-am-homepage.md +0 -0
  47. package/docs/step-definitions/given-i-am-specific-page.md +0 -0
  48. package/docs/step-definitions/then-i-should-be.md +0 -0
  49. package/docs/step-definitions/then-i-should-see.md +6 -0
  50. package/docs/step-definitions/then-item-checkbox.md +0 -0
  51. package/docs/step-definitions/then-item-link-should-contain-url.md +0 -0
  52. package/docs/step-definitions/then-item-should-contain.md +0 -0
  53. package/docs/step-definitions/then-radio-button-value-should-be-selected.md +0 -0
  54. package/docs/step-definitions/then-response-status-code-should-be-number.md +0 -0
  55. package/docs/step-definitions/then-value-radio-button-selected.md +0 -0
  56. package/docs/step-definitions/when-i-attach-file-file-name-element.md +0 -0
  57. package/docs/step-definitions/when-i-check-checkbox.md +0 -0
  58. package/docs/step-definitions/when-i-click-link.md +0 -0
  59. package/docs/step-definitions/when-i-click-operation-text-row.md +0 -0
  60. package/docs/step-definitions/when-i-fill.md +0 -0
  61. package/docs/step-definitions/when-i-go-homepage.md +0 -0
  62. package/docs/step-definitions/when-i-go-specific-page.md +0 -0
  63. package/docs/step-definitions/when-i-move-backward-one-page.md +0 -0
  64. package/docs/step-definitions/when-i-move-forward-one-page.md +0 -0
  65. package/docs/step-definitions/when-i-press-button.md +0 -0
  66. package/docs/step-definitions/when-i-reload-page.md +0 -0
  67. package/docs/step-definitions/when-i-scroll.md +0 -0
  68. package/docs/step-definitions/when-i-select-option-select-list.md +0 -0
  69. package/docs/step-definitions/when-i-select-radio-button-value.md +0 -0
  70. package/docs/step-definitions/when-i-uncheck-checkbox.md +0 -0
  71. package/docs/step-definitions/when-i-wait-ajax-finish.md +0 -0
  72. package/docs/step-definitions/when-i-wait.md +0 -0
  73. package/docs/step-definitions.md +0 -0
  74. package/examples/a11y.html +8 -0
  75. package/examples/account.html +0 -0
  76. package/examples/ajax-wait-examples.html +0 -0
  77. package/examples/cookies.html +0 -0
  78. package/examples/date.html +0 -0
  79. package/examples/dynamic-examples.html +0 -0
  80. package/examples/element-visibility.html +17 -0
  81. package/examples/element.html +0 -0
  82. package/examples/field.html +0 -0
  83. package/examples/keyboard.html +0 -0
  84. package/examples/links.html +0 -0
  85. package/examples/modal.html +0 -0
  86. package/examples/native-dialogs.html +22 -0
  87. package/examples/never-settles.html +32 -0
  88. package/examples/path.html +0 -0
  89. package/examples/table.html +0 -0
  90. package/examples/test--modal-dialogs.html +0 -0
  91. package/examples/test--when--i-additionally-select.html +0 -0
  92. package/examples/test--when--i-select-radio-button.html +0 -0
  93. package/examples/video-demo.html +0 -0
  94. package/examples/web-first-text.html +18 -0
  95. package/package.json +2 -2
  96. package/playwright.config.ts +0 -0
  97. package/tests/assets/test-document.pdf +0 -0
  98. package/tests/features/a11y.feature +22 -0
  99. package/tests/features/ajax-wait-examples.feature +0 -0
  100. package/tests/features/cookie.feature +0 -0
  101. package/tests/features/date.feature +0 -0
  102. package/tests/features/dynamic-content-examples.feature +0 -0
  103. package/tests/features/element.feature +0 -0
  104. package/tests/features/field.feature +0 -0
  105. package/tests/features/keyboard.feature +0 -0
  106. package/tests/features/link.feature +0 -0
  107. package/tests/features/modal-advanced-example.feature +0 -0
  108. package/tests/features/modal-basic-example.feature +0 -0
  109. package/tests/features/modal-error-handling-example.feature +0 -0
  110. package/tests/features/modal.feature +0 -0
  111. package/tests/features/path.feature +0 -0
  112. package/tests/features/pronoun-prefix-steps.feature +81 -0
  113. package/tests/features/response.feature +0 -0
  114. package/tests/features/responsive.feature +0 -0
  115. package/tests/features/smart-settle-budget.feature +12 -0
  116. package/tests/features/table.feature +0 -0
  117. package/tests/features/test--given--i-am-an-anonymous-user.feature +0 -0
  118. package/tests/features/test--then--i-save-screenshot.feature +0 -0
  119. package/tests/features/test--then--i-see-locator.feature +0 -0
  120. package/tests/features/test--then--i-should-not-see-an-element.feature +11 -1
  121. package/tests/features/test--then--i-should-see-n-elements.feature +0 -0
  122. package/tests/features/test--then--print-current-url-and-response.feature +0 -0
  123. package/tests/features/test--when--i-additionally-select.feature +0 -0
  124. package/tests/features/test--when--i-follow.feature +0 -0
  125. package/tests/features/test--when--i-select-radio-button.feature +0 -0
  126. package/tests/features/video.feature +0 -0
  127. package/tests/features/wait.feature +0 -0
  128. package/tests/features/web-first-text.feature +21 -0
  129. package/tests/features/yaml.feature +0 -0
  130. package/tests/reports/README.md +0 -0
  131. package/tests/selectors/_canonical-keys.json +0 -0
  132. package/tests/selectors/back-end-selectors.json +0 -0
  133. package/tests/selectors/cms-contentful-admin.json +0 -0
  134. package/tests/selectors/cms-craft-admin.json +0 -0
  135. package/tests/selectors/cms-drupal-cms-gin.json +0 -0
  136. package/tests/selectors/cms-drupal-core-claro.json +0 -0
  137. package/tests/selectors/cms-generic-admin.json +0 -0
  138. package/tests/selectors/cms-ghost-admin.json +0 -0
  139. package/tests/selectors/cms-joomla-admin.json +0 -0
  140. package/tests/selectors/cms-magento2-admin.json +0 -0
  141. package/tests/selectors/cms-prestashop-admin.json +0 -0
  142. package/tests/selectors/cms-shopify-admin.json +0 -0
  143. package/tests/selectors/cms-strapi-admin.json +0 -0
  144. package/tests/selectors/cms-typo3-admin.json +0 -0
  145. package/tests/selectors/cms-woocommerce-front.json +0 -0
  146. package/tests/selectors/cms-wordpress-admin.json +0 -0
  147. package/tests/selectors/framework-ant-design.json +0 -0
  148. package/tests/selectors/framework-bootstrap.json +0 -0
  149. package/tests/selectors/framework-bulma.json +0 -0
  150. package/tests/selectors/framework-chakra.json +0 -0
  151. package/tests/selectors/framework-foundation.json +0 -0
  152. package/tests/selectors/framework-material-ui.json +0 -0
  153. package/tests/selectors/framework-shadcn.json +0 -0
  154. package/tests/selectors/framework-tailwind.json +0 -0
  155. package/tests/selectors/framework-vuetify.json +0 -0
  156. package/tests/selectors/front-end-selectors.json +0 -0
  157. package/tests/selectors/homepage-selectors.json +0 -0
  158. package/tests/step-definitions/a11y.steps.js +340 -114
  159. package/tests/step-definitions/action.steps.js +0 -0
  160. package/tests/step-definitions/api.steps.js +0 -0
  161. package/tests/step-definitions/assertion.steps.js +18 -3
  162. package/tests/step-definitions/auth.steps.js +1 -1
  163. package/tests/step-definitions/clock.steps.js +2 -2
  164. package/tests/step-definitions/cookie.steps.js +0 -0
  165. package/tests/step-definitions/debug.steps.js +0 -0
  166. package/tests/step-definitions/dialog.steps.js +4 -4
  167. package/tests/step-definitions/element.steps.js +0 -0
  168. package/tests/step-definitions/field.steps.js +0 -0
  169. package/tests/step-definitions/file-download.steps.js +0 -0
  170. package/tests/step-definitions/form.steps.js +0 -0
  171. package/tests/step-definitions/iframe.steps.js +1 -1
  172. package/tests/step-definitions/input.steps.js +0 -0
  173. package/tests/step-definitions/javascript.steps.js +0 -0
  174. package/tests/step-definitions/keyboard.steps.js +0 -0
  175. package/tests/step-definitions/link.steps.js +0 -0
  176. package/tests/step-definitions/metatag.steps.js +0 -0
  177. package/tests/step-definitions/modal.steps.js +0 -0
  178. package/tests/step-definitions/navigation.steps.js +0 -0
  179. package/tests/step-definitions/network.steps.js +1 -1
  180. package/tests/step-definitions/path.steps.js +0 -0
  181. package/tests/step-definitions/response.steps.js +0 -0
  182. package/tests/step-definitions/responsive.steps.js +0 -0
  183. package/tests/step-definitions/rest.steps.js +0 -0
  184. package/tests/step-definitions/screenshot.steps.js +0 -0
  185. package/tests/step-definitions/scroll.steps.js +0 -0
  186. package/tests/step-definitions/selectors.steps.js +0 -0
  187. package/tests/step-definitions/storage.steps.js +0 -0
  188. package/tests/step-definitions/table.steps.js +0 -0
  189. package/tests/step-definitions/video.steps.js +0 -0
  190. package/tests/step-definitions/wait.steps.js +3 -3
  191. package/tests/step-definitions/web-first.steps.js +14 -3
  192. package/tests/step-definitions/webship.js +57 -20
  193. package/tests/step-definitions/xml.steps.js +1 -1
  194. package/tests/step-definitions/yaml.steps.js +1 -1
  195. package/tsconfig.json +0 -0
  196. package/videos/README.md +0 -0
@@ -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
  /**
@@ -761,7 +889,7 @@ Then(/^the page should not violate the accessibility rule "([^"]*)"$/, async fun
761
889
  * Then I print accessibility violations
762
890
  *
763
891
  */
764
- Then(/^(I |we )*print accessibility violations$/, async function () {
892
+ Then(/^(I |we )*print accessibility violations$/, async function (pronounCase) {
765
893
  const result = await runAxe(this);
766
894
  if (result.violations.length === 0) {
767
895
  console.log('\n--- Accessibility violations: none ---');
@@ -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
+ });
File without changes
File without changes
@@ -86,17 +86,32 @@ Then(/^(I |we )*should( not)* see "([^"]*)?" in( the)* "([^"]*)?" row$/, async f
86
86
  // ---------------------------------------------------------------------------
87
87
 
88
88
  /**
89
- * Assert that an element with a given label exists (or does not) on the page.
89
+ * Assert that an element is, or is not, visible on the page. The element is
90
+ * named by its exact visible text; a `<label for="...">` stands for the
91
+ * control it labels. The text is not a CSS selector: for a selector use
92
+ * `"<selector>" should be visible` or `"<selector>" should not be visible`.
93
+ *
94
+ * "should not see" is the opposite of "should see": it passes when no element
95
+ * named that way is visible, so an element that is hidden does not fail it.
90
96
  *
91
97
  * Example #1: Then I should see a "Username" element
92
98
  * Example #2: Then I should not see a "Username" element
93
99
  * Example #3: And we should see an "Email" element
100
+ * Example #4: Then I should not see an "Email" element
101
+ * Example #5: And we should not see a "Promo banner" element
94
102
  *
95
103
  */
96
104
  Then(/^(I |we )*should( not)* see (a|an) "([^"]*)?" element$/, async function (pronounCase, notCase, aAnCase, element) {
97
105
  if (notCase) {
98
- const text = await this.page.locator('body').textContent() || '';
99
- assert.ok(!text.includes(element), `Page should NOT contain element text "${element}" but it does.`);
106
+ // Same lookup as the positive branch, over every match, without waiting.
107
+ const named = this.page.getByText(element, { exact: true });
108
+ const forIds = await named.evaluateAll((nodes) => nodes.map((node) => node.getAttribute('for')));
109
+ for (let i = 0; i < forIds.length; i++) {
110
+ const target = forIds[i]
111
+ ? this.page.locator(`[id="${forIds[i].replace(/["\\]/g, '\\$&')}"]`).first()
112
+ : named.nth(i);
113
+ assert.ok(!(await target.isVisible()), `Element "${element}" should NOT be visible but it is.`);
114
+ }
100
115
  } else {
101
116
  const loc = this.page.getByText(element, { exact: true }).first();
102
117
  const forAttr = await loc.getAttribute('for').catch(() => null);
@@ -115,7 +115,7 @@ Given(/^(I |we )*restore the auth state from "([^"]*)"$/, async function (pronou
115
115
  * Then I should see "Login"
116
116
  *
117
117
  */
118
- Given(/^(I |we )*clear the auth state$/, async function () {
118
+ Given(/^(I |we )*clear the auth state$/, async function (pronoun) {
119
119
  await this.context.clearCookies();
120
120
  try {
121
121
  await this.page.evaluate(() => {
@@ -85,7 +85,7 @@ When(/^(I |we )*advance the clock by (\d+) minutes?$/, async function (pronoun,
85
85
  * Example #5: When I pause the clock
86
86
  *
87
87
  */
88
- When(/^(I |we )*pause the clock$/, async function () {
88
+ When(/^(I |we )*pause the clock$/, async function (pronoun) {
89
89
  try { await this.page.clock.pauseAt(await this.page.evaluate(() => Date.now())); }
90
90
  catch (e) { throw friendly({ action: 'pause the clock', cause: e, hint: ISO_HINT }); }
91
91
  });
@@ -100,7 +100,7 @@ When(/^(I |we )*pause the clock$/, async function () {
100
100
  * Example #5: When I resume the clock
101
101
  *
102
102
  */
103
- When(/^(I |we )*resume the clock$/, async function () {
103
+ When(/^(I |we )*resume the clock$/, async function (pronoun) {
104
104
  try { await this.page.clock.resume(); }
105
105
  catch (e) { throw friendly({ action: 'resume the clock', cause: e, hint: 'pause the clock first via "When I pause the clock".' }); }
106
106
  });
File without changes