@watershed-labs/a11y

Accessibility scanning, WCAG 2.2 helpers, and ARIA assertions for the Watershed ecosystem.

Part of the Watershed testing ecosystem.

Overview

@watershed-labs/a11y wraps @axe-core/webdriverjs with pre-configured WCAG 2.2 rule sets and adds helpers for the criteria axe-core does not cover automatically — focus visibility, target size, and ARIA live region assertions via WebDriver BiDi DOM mutation events.

It lives as a shared package rather than inside create-otter because create-egret and create-salamander both require accessibility scanning too. One implementation, consistently applied across all browser and mobile templates.

axe-core covers approximately 40–60% of WCAG 2.2 success criteria automatically. The remainder requires manual testing. Automated scanning is a necessary floor, not a ceiling.

Installation

npm install @watershed-labs/a11y

Usage

import { A11yScanner } from '@watershed-labs/a11y';

const scanner = new A11yScanner(driver);

// Full page scan
const results = await scanner.scan({ wcagLevel: 'AA' });
await scanner.assertNoViolations(results);

// Scoped to a region
const results = await scanner.scan({
    context: '#checkout-form',
    wcagLevel: 'AA',
});

// WCAG 2.2 — new criteria helpers
await scanner.assertFocusVisible(submitButton);
await scanner.assertTargetSize(submitButton);

// ARIA live region — uses BiDi DOM mutation events
await scanner.assertLiveRegion('[role="status"]', 'Order placed successfully');

API

| Method | Description | |---|---| | scan(options?) | Runs axe-core on the current page or scoped context. Returns structured violation results. | | assertNoViolations(results) | Throws a formatted, readable error if any critical or serious violations are present. | | assertFocusVisible(element) | Asserts that the element has a visible focus indicator. Uses computed style check. WCAG 2.2 criterion 2.4.7. | | assertTargetSize(element, minPx?) | Asserts WCAG 2.2 criterion 2.5.8 minimum interactive target size. Default 24px. | | assertLiveRegion(selector, expectedText) | Uses BiDi DOM mutation events to assert that an ARIA live region updates with the expected text. |

WCAG 2.2 Coverage

| Criterion | Method | Coverage type | |---|---|---| | 1.1.1 Non-text Content | scan() | Automated | | 1.4.3 Colour Contrast AA | scan() | Automated | | 1.4.11 Non-text Contrast | scan() | Automated | | 2.1.1 Keyboard Accessible | Manual scenario | Manual | | 2.4.7 Focus Visible | assertFocusVisible() | Automated | | 2.5.8 Target Size Minimum | assertTargetSize() | Automated | | 4.1.2 Name, Role, Value | scan() | Automated | | 4.1.3 Status Messages | assertLiveRegion() | Automated |

Parallel Safety

Safe. Each A11yScanner instance holds a reference to a single driver session. Workers never share scanner instances.

Dependency

Requires @axe-core/webdriverjs — the correct Selenium integration package. @axe-core/selenium does not exist.

Licence

MIT — part of the Watershed ecosystem.