@vardot/varbase-e2e 2.0.0

package/docs/steps/a11y.md

@@ -0,0 +1,731 @@
+# Accessibility steps
+
+26 steps, defined in `tests/step-definitions/a11y.steps.js`.
+
+Cucumber-js loads every `*.steps.js` in that directory automatically — you never `require()` a step file from a feature.
+
+| # | Step |
+| --- | --- |
+| 1 | `Then every image should have an alt attribute` |
+| 2 | `Then every form field should have an accessible label` |
+| 3 | `Then the page should have a main landmark` |
+| 4 | `Then the page should have a navigation landmark` |
+| 5 | `Then the page should have exactly one h1` |
+| 6 | `Then the focused element should match "#email"` |
+| 7 | `Then the focused element should be labeled "Email"` |
+| 8 | `Then the page should declare a language` |
+| 9 | `Then the page language should be "en"` |
+| 10 | `Then the heading hierarchy should be valid` |
+| 11 | `Then the page should have a skip link` |
+| 12 | `Then every button should have an accessible name` |
+| 13 | `Then every link should have an accessible name` |
+| 14 | `Then no element should have a positive tabindex` |
+| 15 | `Then every ARIA reference should resolve` |
+| 16 | `Then every ARIA role should be valid` |
+| 17 | `Then required fields should be consistently marked` |
+| 18 | `Then the page should have a title` |
+| 19 | `Then user zoom should be allowed` |
+| 20 | `Then the page should pass an accessibility audit` |
+| 21 | `Then the page should have no critical accessibility violations` |
+| 22 | `Then the element "main" should pass an accessibility audit` |
+| 23 | `Then the page should pass an accessibility audit excluding "iframe.payment"` |
+| 24 | `Then the page should not violate the accessibility rule "color-contrast"` |
+| 25 | `Then I print accessibility violations` |
+| 26 | `Then the page should pass the accessibility rules "image-alt, label"` |
+
+---
+
+## 1. Then every image should have an alt attribute
+
+Assert every <img> on the page has an `alt` attribute.
+
+Empty `alt=""` is allowed (decorative images per WCAG); `role="presentation"`
+is also allowed. Only a missing `alt` attribute fails. Iterates every <img>
+in the document, including those nested in shadow-light DOM that the page
+has rendered, so it works on infinite-scroll lists and image galleries too.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^every image should have an alt attribute$/
+```
+
+**Examples**
+
+```gherkin
+Then every image should have an alt attribute
+And every image should have an alt attribute
+Given I am on "/photos"
+  Then every image should have an alt attribute
+When I scroll to the bottom
+  Then every image should have an alt attribute
+When I follow "Gallery"
+  Then every image should have an alt attribute
+```
+
+## 2. Then every form field should have an accessible label
+
+Assert every form input/select/textarea has an accessible name.
+
+Pass condition: each field has at least ONE of —
+  - `aria-label` attribute
+  - `aria-labelledby` attribute pointing at a real element
+  - matching `<label for="...">`
+  - wrapping `<label>` element
+
+Submit/reset/button/image inputs and `type="hidden"` are exempt because
+they get their accessible name from `value` or `alt`.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^every form field should have an accessible label$/
+```
+
+**Examples**
+
+```gherkin
+Then every form field should have an accessible label
+Given I am on "/register"
+  Then every form field should have an accessible label
+When I open the settings modal
+  Then every form field should have an accessible label
+And every form field should have an accessible label
+Then the page should have a main landmark
+  And every form field should have an accessible label
+```
+
+## 3. Then the page should have a main landmark
+
+Assert the page has a primary `<main>` (or `[role="main"]`) landmark.
+
+Screen readers announce landmarks; missing the main landmark forces users
+to navigate the page linearly. WCAG 2.4.1 (Bypass Blocks) requires it.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should have a main landmark$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should have a main landmark
+Given I am on "/about"
+  Then the page should have a main landmark
+When I follow "Pricing"
+  Then the page should have a main landmark
+And the page should have a main landmark
+Then the page should have a navigation landmark
+  And the page should have a main landmark
+```
+
+## 4. Then the page should have a navigation landmark
+
+Assert the page has at least one navigation landmark.
+
+Counts both `<nav>` and `[role="navigation"]`.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should have a navigation landmark$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should have a navigation landmark
+Given I am on the homepage
+  Then the page should have a navigation landmark
+Given I am on "/admin"
+  Then the page should have a navigation landmark
+And the page should have a navigation landmark
+Then the page should have exactly one h1
+  And the page should have a navigation landmark
+```
+
+## 5. Then the page should have exactly one h1
+
+Assert the page has exactly one `<h1>`.
+
+Multiple h1s are valid HTML5 with sectioning roots, but most assistive tech
+still treats the document outline as flat. One h1 per page is the safe
+default.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should have exactly one h1$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should have exactly one h1
+Given I am on the homepage
+  Then the page should have exactly one h1
+When I follow "About"
+  Then the page should have exactly one h1
+And the page should have exactly one h1
+Then the page should have a main landmark
+  And the page should have exactly one h1
+```
+
+## 6. Then the focused element should match "#email"
+
+Assert the currently focused element matches a CSS selector.
+
+Useful for tab-order and skip-link tests.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the focused element should match "([^"]*)"$/
+```
+
+**Examples**
+
+```gherkin
+Then the focused element should match "#email"
+When I press the "Tab" key
+  Then the focused element should match "#email"
+When I press the "Tab" key 2 times
+  Then the focused element should match "#password"
+When I focus on the element "#search"
+  Then the focused element should match "input[type=search]"
+When I follow "Skip to main content"
+  Then the focused element should match "main h1"
+```
+
+## 7. Then the focused element should be labeled "Email"
+
+Assert the currently focused element's accessible name contains text.
+
+Resolution order: aria-label → aria-labelledby → label[for] → wrapping
+<label> → value/placeholder/title/textContent.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the focused element should be labeled "([^"]*)"$/
+```
+
+**Examples**
+
+```gherkin
+Then the focused element should be labeled "Email"
+When I press the "Tab" key
+  Then the focused element should be labeled "Email"
+When I press the "Tab" key 2 times
+  Then the focused element should be labeled "Password"
+When I press the "Tab" key 3 times
+  Then the focused element should be labeled "Sign in"
+When I focus on the element "#agree"
+  Then the focused element should be labeled "I agree"
+```
+
+## 8. Then the page should declare a language
+
+Assert the document has a `lang` attribute on `<html>`.
+
+Required by WCAG 3.1.1 — screen readers use `lang` to pick the right
+pronunciation engine. Missing or empty `lang` fails.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should declare a language$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should declare a language
+Given I am on the homepage
+  Then the page should declare a language
+When I follow "About"
+  Then the page should declare a language
+And the page should declare a language
+Then the page should have a main landmark
+  And the page should declare a language
+```
+
+## 9. Then the page language should be "en"
+
+Assert the document `lang` equals an expected value.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page language should be "([^"]*)"$/
+```
+
+**Examples**
+
+```gherkin
+Then the page language should be "en"
+Given I am on the homepage
+  Then the page language should be "en"
+When I switch to the French version
+  Then the page language should be "fr"
+When I switch to the Arabic version
+  Then the page language should be "ar"
+And the page language should be "en-US"
+```
+
+## 10. Then the heading hierarchy should be valid
+
+Assert headings appear in non-skipping order (h1 → h2 → h3 — never
+h1 → h3). Required by WCAG 1.3.1 / 2.4.6 for screen-reader navigation.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the heading hierarchy should be valid$/
+```
+
+**Examples**
+
+```gherkin
+Then the heading hierarchy should be valid
+Given I am on the homepage
+  Then the heading hierarchy should be valid
+When I follow "About"
+  Then the heading hierarchy should be valid
+And the heading hierarchy should be valid
+Then the page should have exactly one h1
+  And the heading hierarchy should be valid
+```
+
+## 11. Then the page should have a skip link
+
+Assert the page exposes a skip-link as the first focusable element. WCAG
+2.4.1 requires a mechanism to bypass repeated content blocks.
+
+Detection: anchor with href="#..." that resolves to an existing target
+AND text matching "skip" / "main content" / "to content".
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should have a skip link$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should have a skip link
+Given I am on the homepage
+  Then the page should have a skip link
+When I press the key "Tab"
+  Then the focused element should match "a[href^='#']"
+  And the page should have a skip link
+Then the page should have a skip link
+  And the page should have a main landmark
+When I follow "About"
+  Then the page should have a skip link
+```
+
+## 12. Then every button should have an accessible name
+
+Assert every <button> / role="button" has an accessible name (visible
+text, aria-label, or aria-labelledby).
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^every button should have an accessible name$/
+```
+
+**Examples**
+
+```gherkin
+Then every button should have an accessible name
+Given I am on the homepage
+  Then every button should have an accessible name
+When I am on "/checkout"
+  Then every button should have an accessible name
+And every button should have an accessible name
+Then every button should have an accessible name
+  And every link should have an accessible name
+```
+
+## 13. Then every link should have an accessible name
+
+Assert every <a> has an accessible name.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^every link should have an accessible name$/
+```
+
+**Examples**
+
+```gherkin
+Then every link should have an accessible name
+Given I am on the homepage
+  Then every link should have an accessible name
+When I am on "/blog"
+  Then every link should have an accessible name
+And every link should have an accessible name
+Then every button should have an accessible name
+  And every link should have an accessible name
+```
+
+## 14. Then no element should have a positive tabindex
+
+Assert NO interactive element uses a positive `tabindex`. Positive values
+break natural focus order — WCAG 2.4.3 violation in practice.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^no element should have a positive tabindex$/
+```
+
+**Examples**
+
+```gherkin
+Then no element should have a positive tabindex
+Given I am on the homepage
+  Then no element should have a positive tabindex
+When I am on "/form"
+  Then no element should have a positive tabindex
+And no element should have a positive tabindex
+Then no element should have a positive tabindex
+  And the heading hierarchy should be valid
+```
+
+## 15. Then every ARIA reference should resolve
+
+Assert every `aria-labelledby` / `aria-describedby` / `aria-controls`
+/ `aria-owns` references an existing element id.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^every ARIA reference should resolve$/
+```
+
+**Examples**
+
+```gherkin
+Then every ARIA reference should resolve
+Given I am on the homepage
+  Then every ARIA reference should resolve
+When I am on "/dashboard"
+  Then every ARIA reference should resolve
+And every ARIA reference should resolve
+Then every ARIA reference should resolve
+  And every button should have an accessible name
+```
+
+## 16. Then every ARIA role should be valid
+
+Assert no element uses an invalid ARIA role. Reference: WAI-ARIA 1.2.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^every ARIA role should be valid$/
+```
+
+**Examples**
+
+```gherkin
+Then every ARIA role should be valid
+Given I am on the homepage
+  Then every ARIA role should be valid
+When I am on "/dashboard"
+  Then every ARIA role should be valid
+And every ARIA role should be valid
+Then every ARIA role should be valid
+  And every ARIA reference should resolve
+```
+
+## 17. Then required fields should be consistently marked
+
+Assert every form field exposing `aria-required="true"` is also marked
+with the native `required` attribute (or vice versa). Mismatch confuses
+assistive tech.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^required fields should be consistently marked$/
+```
+
+**Examples**
+
+```gherkin
+Then required fields should be consistently marked
+Given I am on "/signup"
+  Then required fields should be consistently marked
+When I am on "/checkout"
+  Then required fields should be consistently marked
+And required fields should be consistently marked
+Then every form field should have an accessible label
+  And required fields should be consistently marked
+```
+
+## 18. Then the page should have a title
+
+Assert the document has a non-empty `<title>`. WCAG 2.4.2.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should have a title$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should have a title
+Given I am on the homepage
+  Then the page should have a title
+When I am on "/about"
+  Then the page should have a title
+And the page should have a title
+Then the page should have a title
+  And the page should declare a language
+```
+
+## 19. Then user zoom should be allowed
+
+Assert the viewport meta tag does not disable user-scaling
+(`user-scalable=no` or `maximum-scale=1`). WCAG 1.4.4 / 1.4.10.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^user zoom should be allowed$/
+```
+
+**Examples**
+
+```gherkin
+Then user zoom should be allowed
+Given I am on the homepage
+  Then user zoom should be allowed
+When I am on "/article"
+  Then user zoom should be allowed
+And user zoom should be allowed
+Then user zoom should be allowed
+  And the page should declare a language
+```
+
+## 20. Then the page should pass an accessibility audit
+
+Run an axe-core audit and assert ZERO violations across the supplied WCAG
+level. Defaults to AA — the level mandated by most accessibility laws.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should pass an accessibility audit(?: at level "(A|AA|AAA)")?$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should pass an accessibility audit
+Then the page should pass an accessibility audit at level "A"
+Then the page should pass an accessibility audit at level "AA"
+And the page should pass an accessibility audit at level "AAA"
+When I am on "/dashboard"
+  Then the page should pass an accessibility audit at level "AA"
+```
+
+## 21. Then the page should have no critical accessibility violations
+
+Assert NO axe violations of the given impact severity.
+Levels: `minor`, `moderate`, `serious`, `critical`.
+
+Use to gate merges on critical/serious issues while triaging minor regressions.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should have no (critical|serious|moderate|minor) accessibility violations$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should have no critical accessibility violations
+Then the page should have no serious accessibility violations
+And the page should have no moderate accessibility violations
+When I am on "/checkout"
+  Then the page should have no critical accessibility violations
+Then the page should have no critical accessibility violations
+  And the page should have no serious accessibility violations
+```
+
+## 22. Then the element "main" should pass an accessibility audit
+
+Audit ONLY the subtree under a CSS selector. Use when third-party widgets
+are known-bad and you only want to gate your own components.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the element "([^"]*)" should pass an accessibility audit$/
+```
+
+**Examples**
+
+```gherkin
+Then the element "main" should pass an accessibility audit
+Then the element "#checkout-form" should pass an accessibility audit
+And the element ".product-card" should pass an accessibility audit
+Then the element "#dashboard-widget" should pass an accessibility audit
+Then the element "[data-testid=signup]" should pass an accessibility audit
+```
+
+## 23. Then the page should pass an accessibility audit excluding "iframe.payment"
+
+Audit the page but EXCLUDE the subtree under a CSS selector. Skip
+known-bad embedded content (third-party iframes, legacy widgets, ads).
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should pass an accessibility audit excluding "([^"]*)"$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should pass an accessibility audit excluding "iframe.payment"
+Then the page should pass an accessibility audit excluding "#chat-widget"
+And the page should pass an accessibility audit excluding ".legacy-banner"
+Then the page should pass an accessibility audit excluding "[data-third-party]"
+Then the page should pass an accessibility audit excluding ".ads"
+```
+
+## 24. Then the page should not violate the accessibility rule "color-contrast"
+
+Assert a specific axe rule does not fire. Use for fine-grained gates —
+e.g. ensure color-contrast is fixed even if other rules still red.
+
+Common rule ids: `color-contrast`, `image-alt`, `label`, `link-name`,
+`button-name`, `heading-order`, `landmark-one-main`, `region`,
+`aria-valid-attr`, `tabindex`, `bypass`, `frame-title`, `meta-viewport`,
+`valid-lang`, `duplicate-id-aria`, `list`, `listitem`.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should not violate the accessibility rule "([^"]*)"$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should not violate the accessibility rule "color-contrast"
+Then the page should not violate the accessibility rule "image-alt"
+And the page should not violate the accessibility rule "label"
+Then the page should not violate the accessibility rule "link-name"
+Then the page should not violate the accessibility rule "heading-order"
+```
+
+## 25. Then I print accessibility violations
+
+Print every axe violation to stdout (debug aid). Strip from CI runs.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^(I |we )*print accessibility violations$/
+```
+
+**Examples**
+
+```gherkin
+Then I print accessibility violations
+When I am on "/checkout"
+  Then I print accessibility violations
+And we print accessibility violations
+Then I print accessibility violations
+  And the page should have no critical accessibility violations
+When I follow "Pricing"
+  Then I print accessibility violations
+```
+
+## 26. Then the page should pass the accessibility rules "image-alt, label"
+
+Assert axe finds zero violations of an exact list of rules. Use for
+smoke-test gating: pin the small list of rules you absolutely require to
+pass, run them on every page.
+
+**Keyword**: `Then`
+
+**Pattern**
+
+```js
+/^the page should pass the accessibility rules "([^"]*)"$/
+```
+
+**Examples**
+
+```gherkin
+Then the page should pass the accessibility rules "image-alt, label"
+Then the page should pass the accessibility rules "color-contrast"
+And the page should pass the accessibility rules "button-name, link-name"
+Then the page should pass the accessibility rules "landmark-one-main, region"
+Then the page should pass the accessibility rules "aria-valid-attr, aria-valid-attr-value"
+```