Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

test(a11y): expose accessibility spec assertions (#6176)

Cindy Zhang491945a49d66
diff --git a/internal/a11y-spec/README.md b/internal/a11y-spec/README.md
index 065d676a77..d3e621662d 100644
--- a/internal/a11y-spec/README.md
+++ b/internal/a11y-spec/README.md
@@ -31,7 +31,8 @@ src/
├── contract.ts Expectation, PatternContract, definePattern (the schema gate)
├── checklist.ts the completeness dimensions every pattern must answer
├── harness.ts the Harness/Subject seam and the evidence-layer vocabulary
-├── run.ts runBinding — applicability, unrun layers, known failures
+├── check.ts checkAccessibilitySpec — low-level result for reports/mutation proof
+├── expect.ts expectAccessibilitySpec — component-facing render + subject assertion
├── report.ts separate facts, and the gate over them
├── harness/
│ ├── jsdom.ts observes unit + DOM. Refuses everything above.
@@ -153,6 +154,26 @@ exactly the expectation under test instead of making the subject unfindable.
Component-specific behaviour does not move: callbacks, form data, composition,
and styling stay in the component's own suite (AST-021 FR5).
+The fast component lane uses the assertion API directly, so the test visibly names
+the accessibility specification, the component render, and its role-bearing subject:
+
+```tsx
+await expectAccessibilitySpec({
+ spec: BUTTON_PATTERN,
+ binding: state.binding,
+ state: state.id,
+ facts: state.facts,
+ render: () => render(<Button label="Save" />),
+ subject: () => screen.getByRole('button'),
+ cleanup,
+});
+```
+
+`expectAccessibilitySpec` fails the test on required failures and unexpected passes.
+Lower-level contract fixtures, Chromium bindings, report generation, and mutation
+proof use `checkAccessibilitySpec`, which returns the complete factual result without
+asserting it.
+
## Known failures
A known failure names one expectation, one binding, one state, one evidence
diff --git a/internal/a11y-spec/src/run.test.ts b/internal/a11y-spec/src/check.test.ts
similarity index 97%
rename from internal/a11y-spec/src/run.test.ts
rename to internal/a11y-spec/src/check.test.ts
index 9a12002638..15e209713a 100644
--- a/internal/a11y-spec/src/run.test.ts
+++ b/internal/a11y-spec/src/check.test.ts
@@ -1,8 +1,8 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file run.test.ts
- * @input Uses ./contract, ./run, ./report and a stub harness
+ * @file check.test.ts
+ * @input Uses ./contract, ./check, ./report and a stub harness
* @output Proof that a known failure changes only its own exact result, that an
* unobservable layer is reported rather than passed, and that the report
* keeps its facts apart.
@@ -23,7 +23,11 @@ import {
neverExercised,
summarize,
} from './report';
-import {runBinding, unmatchedKnownFailures, type KnownFailure} from './run';
+import {
+ checkAccessibilitySpec,
+ unmatchedKnownFailures,
+ type KnownFailure,
+} from './check';
interface Facts {
readonly applicable: boolean;
@@ -102,7 +106,7 @@ function knownFailure(overrides: Partial<KnownFailure> = {}): KnownFailure {
}
async function run(
- contract: PatternContract<Facts>,
+ spec: PatternContract<Facts>,
options: {
facts?: Facts;
knownFailures?: readonly KnownFailure[];
@@ -110,8 +114,8 @@ async function run(
state?: string;
} = {},
) {
- return runBinding({
- contract,
+ return checkAccessibilitySpec({
+ spec,
binding: 'Stub',
state: options.state ?? 'default',
facts: options.facts ?? {applicable: true},
@@ -124,7 +128,7 @@ const missing = () => {
throw new Error('the stub outcome is missing entirely');
};
-describe('runBinding', () => {
+describe('checkAccessibilitySpec', () => {
it('passes when the outcome happens', async () => {
const result = await run(contractThat(() => {}));
expect(result.results[0]?.status).toBe('pass');
@@ -361,8 +365,8 @@ describe('runBinding', () => {
it('lets a broken mount surface instead of absorbing it as a result', async () => {
await expect(
- runBinding({
- contract: contractThat(() => {}),
+ checkAccessibilitySpec({
+ spec: contractThat(() => {}),
binding: 'Stub',
state: 'default',
facts: {applicable: true},
diff --git a/internal/a11y-spec/src/run.ts b/internal/a11y-spec/src/check.ts
similarity index 95%
rename from internal/a11y-spec/src/run.ts
rename to internal/a11y-spec/src/check.ts
index 8037cbd526..df6f53165e 100644
--- a/internal/a11y-spec/src/run.ts
+++ b/internal/a11y-spec/src/check.ts
@@ -1,9 +1,9 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @file run.ts
+ * @file check.ts
* @input Uses ./contract (expectations), ./harness (the runtime seam)
- * @output `runBinding` — runs one pattern contract against one component binding
+ * @output `checkAccessibilitySpec` — runs one pattern contract against one component binding
* state — plus the known-failure vocabulary and exact-record reconciliation
* helpers it obeys.
* @position The engine between a pattern and a component. Everything a report
@@ -103,8 +103,8 @@ export interface BindingResult {
readonly results: readonly ExpectationResult[];
}
-export interface RunBindingOptions<Facts> {
- readonly contract: PatternContract<Facts>;
+export interface CheckAccessibilitySpecOptions<Facts> {
+ readonly spec: PatternContract<Facts>;
readonly binding: string;
readonly state: string;
readonly facts: Facts;
@@ -136,7 +136,7 @@ export interface RunBindingOptions<Facts> {
/**
* Thrown when an expectation reads something only the binding can supply and
* the binding did not supply it. A binding fault, not a contract result: it
- * escapes `runBinding` rather than being recorded as a failure, because the
+ * escapes `checkAccessibilitySpec` rather than being recorded as a failure, because the
* outcome was never actually tested.
*/
export class MissingBindingCapability extends Error {
@@ -181,15 +181,15 @@ export function unmatchedKnownFailures(
});
}
-export async function runBinding<Facts>(
- options: RunBindingOptions<Facts>,
+export async function checkAccessibilitySpec<Facts>(
+ options: CheckAccessibilitySpecOptions<Facts>,
): Promise<BindingResult> {
- const {contract, binding, state, facts, mount, unmount} = options;
+ const {spec, binding, state, facts, mount, unmount} = options;
const knownFailures = options.knownFailures ?? [];
const results: ExpectationResult[] = [];
let harnessName = 'unmounted';
- for (const expectation of contract.expectations) {
+ for (const expectation of spec.expectations) {
if (options.only != null && !options.only.includes(expectation.id)) {
continue;
}
@@ -320,7 +320,7 @@ export async function runBinding<Facts>(
}
return {
- pattern: contract.pattern,
+ pattern: spec.pattern,
binding,
state,
harness: harnessName,
diff --git a/internal/a11y-spec/src/expect.test.ts b/internal/a11y-spec/src/expect.test.ts
new file mode 100644
index 0000000000..aa509cb4f6
--- /dev/null
+++ b/internal/a11y-spec/src/expect.test.ts
@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+// @vitest-environment jsdom
+
+/**
+ * @file expect.test.ts
+ * @input Uses one minimal accessibility spec and the jsdom assertion helper
+ * @output Proof that component-facing tests pass render and subject explicitly,
+ * and that required failures reject with a reader-legible message
+ * @position Public test-API contract for expectAccessibilitySpec
+ */
+
+import {describe, expect, it, vi} from 'vitest';
+import {definePattern} from './contract';
+import {expectAccessibilitySpec} from './expect';
+
+interface Facts {
+ readonly present: boolean;
+}
+
+const SPEC = definePattern<Facts>({
+ pattern: 'probe',
+ url: 'https://example.invalid/probe',
+ scope: 'A minimal pattern for testing the assertion API.',
+ exemptions: {},
+ expectations: [
+ {
+ id: 'probe.name.present',
+ outcome: 'The probe has a name.',
+ sources: [
+ {
+ standard: 'wcag',
+ id: '4.1.2',
+ name: 'Name, Role, Value',
+ level: 'A',
+ url: 'https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html',
+ },
+ ],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the probe is present',
+ test: facts => facts.present,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ if ((await subject.attribute('aria-label')) !== 'Save') {
+ throw new Error('the probe has no accessible name');
+ }
+ },
+ },
+ ],
+});
+
+describe('expectAccessibilitySpec', () => {
+ it('accepts render and subject directly and resolves when the spec passes', async () => {
+ const render = vi.fn(() => {
+ document.body.innerHTML = '<button aria-label="Save">Save</button>';
+ });
+
+ await expectAccessibilitySpec({
+ spec: SPEC,
+ binding: 'Button',
+ state: 'default',
+ facts: {present: true},
+ render,
+ subject: () => document.querySelector('button')!,
+ cleanup: () => {
+ document.body.innerHTML = '';
+ },
+ });
+
+ expect(render).toHaveBeenCalledOnce();
+ });
+
+ it('rejects with the binding and failed outcome when a required check fails', async () => {
+ await expect(
+ expectAccessibilitySpec({
+ spec: SPEC,
+ binding: 'Button',
+ state: 'unnamed',
+ facts: {present: true},
+ render: () => {
+ document.body.innerHTML = '<button>Save</button>';
+ },
+ subject: () => document.querySelector('button')!,
+ cleanup: () => {
+ document.body.innerHTML = '';
+ },
+ }),
+ ).rejects.toThrow(/Button \[unnamed\].*probe\.name\.present/s);
+ });
+});
diff --git a/internal/a11y-spec/src/expect.ts b/internal/a11y-spec/src/expect.ts
new file mode 100644
index 0000000000..c4c909983d
--- /dev/null
+++ b/internal/a11y-spec/src/expect.ts
@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file expect.ts
+ * @input Uses the accessibility spec checker, jsdom harness, and failure formatter
+ * @output `expectAccessibilitySpec` — the component-facing assertion helper with
+ * explicit render and subject seams
+ * @position Test API. Component suites use this; reports and mutation proof use
+ * the lower-level `checkAccessibilitySpec` evaluator.
+ */
+
+import type {PatternContract} from './contract';
+import {createJsdomHarness} from './harness/jsdom';
+import {blockingResults, formatFailures} from './report';
+import {
+ checkAccessibilitySpec,
+ type BindingResult,
+ type CheckAccessibilitySpecOptions,
+} from './check';
+
+export interface ExpectAccessibilitySpecOptions<Facts> extends Omit<
+ CheckAccessibilitySpecOptions<Facts>,
+ 'spec' | 'mount' | 'unmount'
+> {
+ /** The reusable accessibility specification this component state adopts. */
+ readonly spec: PatternContract<Facts>;
+ /** Render the actual component state under test. Called fresh per expectation. */
+ readonly render: () => Promise<void> | void;
+ /** Resolve the role-bearing element the specification checks. */
+ readonly subject: () => Promise<Element> | Element;
+ /** Remove the rendered state between expectations. */
+ readonly cleanup?: () => Promise<void> | void;
+}
+
+/**
+ * Check one rendered component state and fail the test when a required
+ * accessibility expectation fails or a known failure unexpectedly passes.
+ */
+export async function expectAccessibilitySpec<Facts>(
+ options: ExpectAccessibilitySpecOptions<Facts>,
+): Promise<BindingResult> {
+ const {spec, render, subject, cleanup, ...binding} = options;
+ const result = await checkAccessibilitySpec({
+ ...binding,
+ spec,
+ mount: async () => {
+ await render();
+ return createJsdomHarness({subject: await subject()});
+ },
+ unmount: cleanup,
+ });
+ const failures = formatFailures(blockingResults([result]));
+ if (failures !== '') {
+ throw new Error(`Accessibility specification failed:\n\n${failures}`);
+ }
+ return result;
+}
diff --git a/internal/a11y-spec/src/index.ts b/internal/a11y-spec/src/index.ts
index b29b227669..918b384fcb 100644
--- a/internal/a11y-spec/src/index.ts
+++ b/internal/a11y-spec/src/index.ts
@@ -51,14 +51,19 @@ export {
export {
MissingBindingCapability,
- runBinding,
+ checkAccessibilitySpec,
unmatchedKnownFailures,
type BindingResult,
+ type CheckAccessibilitySpecOptions,
type ExpectationResult,
type KnownFailure,
type ResultStatus,
- type RunBindingOptions,
-} from './run';
+} from './check';
+
+export {
+ expectAccessibilitySpec,
+ type ExpectAccessibilitySpecOptions,
+} from './expect';
export {
blockingResults,
diff --git a/internal/a11y-spec/src/patterns/button.chromium.spec.ts b/internal/a11y-spec/src/patterns/button.chromium.spec.ts
index 32a013075a..273920976e 100644
--- a/internal/a11y-spec/src/patterns/button.chromium.spec.ts
+++ b/internal/a11y-spec/src/patterns/button.chromium.spec.ts
@@ -3,7 +3,7 @@
/**
* @file button.chromium.spec.ts
* @input Uses @playwright/test, ./button (the contract), ./button.fixtures,
- * ../harness/chromium, ../run
+ * ../harness/chromium, ../check
* @output The contract's own proof in a real engine: every expectation passes
* against a conforming fixture and fails against each fixture that removes
* its outcome.
@@ -27,7 +27,7 @@ import {
createChromiumHarness,
holdMotionStill,
} from '../harness/chromium';
-import {runBinding, type ExpectationResult} from '../run';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
import {BUTTON_PATTERN} from './button';
import {
CONFORMING_FIXTURES,
@@ -57,8 +57,8 @@ async function results(
target: ButtonFixture,
only?: readonly string[],
): Promise<readonly ExpectationResult[]> {
- const run = await runBinding({
- contract: BUTTON_PATTERN,
+ const run = await checkAccessibilitySpec({
+ spec: BUTTON_PATTERN,
binding: 'fixture',
state: target.id,
facts: target.facts,
diff --git a/internal/a11y-spec/src/patterns/button.jsdom.test.ts b/internal/a11y-spec/src/patterns/button.jsdom.test.ts
index a5d3377732..cbd98931ac 100644
--- a/internal/a11y-spec/src/patterns/button.jsdom.test.ts
+++ b/internal/a11y-spec/src/patterns/button.jsdom.test.ts
@@ -4,7 +4,7 @@
/**
* @file button.jsdom.test.ts
* @input Uses ./button (the contract), ./button.fixtures (conforming and
- * violating fixtures), ../harness/jsdom, ../run
+ * violating fixtures), ../harness/jsdom, ../check
* @output The contract's own proof at the DOM layer: every expectation passes
* against a conforming fixture, fails against a fixture that removes its
* outcome, and reports `unrun` when this harness cannot observe its layer.
@@ -28,7 +28,7 @@ import {
unansweredDimensions,
} from '../contract';
import {JSDOM_OBSERVES, createJsdomHarness} from '../harness/jsdom';
-import {runBinding, type ExpectationResult} from '../run';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
import {BUTTON_PATTERN} from './button';
import {
CONFORMING_FIXTURES,
@@ -54,8 +54,8 @@ afterEach(() => {
async function resultsFor(target: ButtonFixture) {
const container = document.createElement('div');
document.body.append(container);
- const result = await runBinding({
- contract: BUTTON_PATTERN,
+ const result = await checkAccessibilitySpec({
+ spec: BUTTON_PATTERN,
binding: 'fixture',
state: target.id,
facts: target.facts,
diff --git a/internal/a11y-spec/src/patterns/checkbox.chromium.spec.ts b/internal/a11y-spec/src/patterns/checkbox.chromium.spec.ts
index 225a5fa082..4b9601f669 100644
--- a/internal/a11y-spec/src/patterns/checkbox.chromium.spec.ts
+++ b/internal/a11y-spec/src/patterns/checkbox.chromium.spec.ts
@@ -3,7 +3,7 @@
/**
* @file checkbox.chromium.spec.ts
* @input Uses @playwright/test, ./checkbox (the contract), ./checkbox.fixtures,
- * ../harness/chromium, ../run
+ * ../harness/chromium, ../check
* @output The contract's own proof in a real engine: every expectation passes
* against a conforming fixture and fails against each fixture that removes
* its outcome.
@@ -27,7 +27,7 @@ import {
createChromiumHarness,
holdMotionStill,
} from '../harness/chromium';
-import {runBinding, type ExpectationResult} from '../run';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
import {CHECKBOX_PATTERN} from './checkbox';
import {
CONFORMING_FIXTURES,
@@ -53,8 +53,8 @@ async function results(
target: CheckboxFixture,
only?: readonly string[],
): Promise<readonly ExpectationResult[]> {
- const run = await runBinding({
- contract: CHECKBOX_PATTERN,
+ const run = await checkAccessibilitySpec({
+ spec: CHECKBOX_PATTERN,
binding: 'fixture',
state: target.id,
facts: target.facts,
diff --git a/internal/a11y-spec/src/patterns/checkbox.jsdom.test.ts b/internal/a11y-spec/src/patterns/checkbox.jsdom.test.ts
index e04f8a9750..49276fa7a6 100644
--- a/internal/a11y-spec/src/patterns/checkbox.jsdom.test.ts
+++ b/internal/a11y-spec/src/patterns/checkbox.jsdom.test.ts
@@ -4,7 +4,7 @@
/**
* @file checkbox.jsdom.test.ts
* @input Uses ./checkbox (the contract), ./checkbox.fixtures (conforming and
- * violating fixtures), ../harness/jsdom, ../run
+ * violating fixtures), ../harness/jsdom, ../check
* @output The contract's own proof at the DOM layer: every expectation passes
* against a conforming fixture, fails against a fixture that removes its
* outcome, and reports `unrun` when this harness cannot observe its layer.
@@ -28,7 +28,7 @@ import {
unansweredDimensions,
} from '../contract';
import {JSDOM_OBSERVES, createJsdomHarness} from '../harness/jsdom';
-import {runBinding, type ExpectationResult} from '../run';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
import {CHECKBOX_PATTERN} from './checkbox';
import {
CONFORMING_FIXTURES,
@@ -50,8 +50,8 @@ afterEach(() => {
async function resultsFor(target: CheckboxFixture) {
const container = document.createElement('div');
document.body.append(container);
- const result = await runBinding({
- contract: CHECKBOX_PATTERN,
+ const result = await checkAccessibilitySpec({
+ spec: CHECKBOX_PATTERN,
binding: 'fixture',
state: target.id,
facts: target.facts,
diff --git a/internal/a11y-spec/src/patterns/switch.chromium.spec.ts b/internal/a11y-spec/src/patterns/switch.chromium.spec.ts
index 3cea1cb12f..6c8fa1c484 100644
--- a/internal/a11y-spec/src/patterns/switch.chromium.spec.ts
+++ b/internal/a11y-spec/src/patterns/switch.chromium.spec.ts
@@ -3,7 +3,7 @@
/**
* @file switch.chromium.spec.ts
* @input Uses @playwright/test, ./switch (the contract), ./switch.fixtures,
- * ../harness/chromium, ../run
+ * ../harness/chromium, ../check
* @output The contract's own proof in a real engine: every expectation passes
* against a conforming fixture and fails against each fixture that removes
* its outcome.
@@ -27,7 +27,7 @@ import {
createChromiumHarness,
holdMotionStill,
} from '../harness/chromium';
-import {runBinding, type ExpectationResult} from '../run';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
import {SWITCH_PATTERN} from './switch';
import {
CONFORMING_FIXTURES,
@@ -52,8 +52,8 @@ async function results(
target: SwitchFixture,
only?: readonly string[],
): Promise<readonly ExpectationResult[]> {
- const run = await runBinding({
- contract: SWITCH_PATTERN,
+ const run = await checkAccessibilitySpec({
+ spec: SWITCH_PATTERN,
binding: 'fixture',
state: target.id,
facts: target.facts,
diff --git a/internal/a11y-spec/src/patterns/switch.jsdom.test.ts b/internal/a11y-spec/src/patterns/switch.jsdom.test.ts
index b1fa474580..d7f56f9b21 100644
--- a/internal/a11y-spec/src/patterns/switch.jsdom.test.ts
+++ b/internal/a11y-spec/src/patterns/switch.jsdom.test.ts
@@ -4,7 +4,7 @@
/**
* @file switch.jsdom.test.ts
* @input Uses ./switch (the contract), ./switch.fixtures (conforming and
- * violating fixtures), ../harness/jsdom, ../run
+ * violating fixtures), ../harness/jsdom, ../check
* @output The contract's own proof at the DOM layer: every expectation passes
* against a conforming fixture, fails against a fixture that removes its
* outcome, and reports `unrun` when this harness cannot observe its layer.
@@ -28,7 +28,7 @@ import {
unansweredDimensions,
} from '../contract';
import {JSDOM_OBSERVES, createJsdomHarness} from '../harness/jsdom';
-import {runBinding, type ExpectationResult} from '../run';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
import {SWITCH_PATTERN} from './switch';
import {
CONFORMING_FIXTURES,
@@ -49,8 +49,8 @@ afterEach(() => {
async function resultsFor(target: SwitchFixture) {
const container = document.createElement('div');
document.body.append(container);
- const result = await runBinding({
- contract: SWITCH_PATTERN,
+ const result = await checkAccessibilitySpec({
+ spec: SWITCH_PATTERN,
binding: 'fixture',
state: target.id,
facts: target.facts,
diff --git a/internal/a11y-spec/src/report.ts b/internal/a11y-spec/src/report.ts
index 05a09e4df9..68c2acfdbf 100644
--- a/internal/a11y-spec/src/report.ts
+++ b/internal/a11y-spec/src/report.ts
@@ -2,7 +2,7 @@
/**
* @file report.ts
- * @input Uses ./run (BindingResult) and ./contract (PatternContract)
+ * @input Uses ./check (BindingResult) and ./contract (PatternContract)
* @output `summarize` and `formatReport` — the facts a reader needs, kept as
* separate facts — plus `blockingResults`, the gate over them, and
* `formatFailures`, the reader-legible failure block bindings assert on.
@@ -15,11 +15,11 @@
* A pattern with one required failure is not "mostly conformant", and there is
* no number in this file that could be mistaken for saying it is.
*
- * SYNC: When ./run.ts gains a status, add it here and to the README table.
+ * SYNC: When ./check.ts gains a status, add it here and to the README table.
*/
import type {PatternContract} from './contract';
-import type {BindingResult, ExpectationResult} from './run';
+import type {BindingResult, ExpectationResult} from './check';
export interface ReportCounts {
readonly pass: number;
diff --git a/packages/core/src/Button/__tests__/Button.a11y.chromium.spec.ts b/packages/core/src/Button/__tests__/Button.a11y.chromium.spec.ts
index 4af3b05751..c9b9cd8406 100644
--- a/packages/core/src/Button/__tests__/Button.a11y.chromium.spec.ts
+++ b/packages/core/src/Button/__tests__/Button.a11y.chromium.spec.ts
@@ -29,7 +29,7 @@ import {
formatReport,
neverExercised,
unmatchedKnownFailures,
- runBinding,
+ checkAccessibilitySpec,
spokenWords,
summarize,
type BindingResult,
@@ -98,8 +98,8 @@ async function runState(
cdp: CDPSession,
state: ButtonBindingRow,
): Promise<BindingResult> {
- return runBinding({
- contract: BUTTON_PATTERN,
+ return checkAccessibilitySpec({
+ spec: BUTTON_PATTERN,
binding: state.binding,
state: state.id,
facts: state.facts,
@@ -134,7 +134,7 @@ function namesTheSameLabel(rendered: string, claimed: string): boolean {
/**
* The inventory AST-021 FR2 asks for, checked against the page rather than
- * trusted. Deliberately NOT part of the shared contract: a wrong entry here is a
+ * trusted. Deliberately NOT part of the shared spec: a wrong entry here is a
* stale inventory, and reporting it as a WCAG 2.5.3 failure would put a metadata
* typo and a real accessibility defect in the same bucket.
*/
@@ -289,8 +289,8 @@ test('every expectation is exercised by at least one bound state', async ({
// would turn a ten-second check into a ten-minute one for no extra truth.
let mounted = false;
results.push(
- await runBinding({
- contract: BUTTON_PATTERN,
+ await checkAccessibilitySpec({
+ spec: BUTTON_PATTERN,
binding: state.binding,
state: state.id,
facts: state.facts,
diff --git a/packages/core/src/Button/__tests__/Button.a11y.test.tsx b/packages/core/src/Button/__tests__/Button.a11y.test.tsx
index 739ffc230f..7bd7eaaac6 100644
--- a/packages/core/src/Button/__tests__/Button.a11y.test.tsx
+++ b/packages/core/src/Button/__tests__/Button.a11y.test.tsx
@@ -26,11 +26,10 @@ import {describe, expect, it} from 'vitest';
import {cleanup, render, screen} from '@testing-library/react';
import {
BUTTON_PATTERN,
- blockingResults,
+ checkAccessibilitySpec,
createJsdomHarness,
- formatFailures,
+ expectAccessibilitySpec,
summarize,
- runBinding,
type BindingResult,
} from '@astryxdesign/a11y-spec';
import {BUTTON_KNOWN_FAILURES} from './Button.a11y.known-failures';
@@ -56,10 +55,32 @@ function subjectFor(): Element {
return screen.getByRole('button', {hidden: true});
}
-async function runState(state: ButtonBindingRow): Promise<BindingResult> {
+async function expectState(state: ButtonBindingRow): Promise<void> {
let activations = 0;
- return runBinding({
- contract: BUTTON_PATTERN,
+ await expectAccessibilitySpec({
+ spec: BUTTON_PATTERN,
+ binding: state.binding,
+ state: state.id,
+ facts: state.facts,
+ knownFailures: BUTTON_KNOWN_FAILURES,
+ render: () => {
+ activations = 0;
+ render(
+ BUTTON_STATE_RENDERS[state.id](() => {
+ activations += 1;
+ }),
+ );
+ },
+ subject: subjectFor,
+ cleanup,
+ activations: async () => activations,
+ });
+}
+
+async function checkState(state: ButtonBindingRow): Promise<BindingResult> {
+ let activations = 0;
+ return checkAccessibilitySpec({
+ spec: BUTTON_PATTERN,
binding: state.binding,
state: state.id,
facts: state.facts,
@@ -85,14 +106,13 @@ describe('the shared button pattern, jsdom lane', () => {
[`${state.binding} [${state.id}]`, state.summary, state] as const,
),
)('%s — %s', async (_id, _summary, state) => {
- const result = await runState(state);
- expect(formatFailures(blockingResults([result]))).toBe('');
+ await expectState(state);
});
it('runs the DOM layer here and reports the higher layers as unrun', async () => {
const results: BindingResult[] = [];
for (const state of BUTTON_BINDING_STATES) {
- results.push(await runState(state));
+ results.push(await checkState(state));
}
const report = summarize(BUTTON_PATTERN, results);
diff --git a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts
index b00e2a4fd8..21ab0d58c4 100644
--- a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts
+++ b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts
@@ -23,7 +23,7 @@ import {
formatReport,
neverExercised,
unmatchedKnownFailures,
- runBinding,
+ checkAccessibilitySpec,
spokenWords,
summarize,
type BindingResult,
@@ -101,8 +101,8 @@ async function runState(
cdp: CDPSession,
state: CheckboxBindingRow,
): Promise<BindingResult> {
- return runBinding({
- contract: CHECKBOX_PATTERN,
+ return checkAccessibilitySpec({
+ spec: CHECKBOX_PATTERN,
binding: state.binding,
state: state.id,
facts: state.facts,
@@ -275,8 +275,8 @@ test('every expectation is exercised by at least one bound state', async ({
for (const state of CHECKBOX_BINDING_STATES) {
let mounted = false;
results.push(
- await runBinding({
- contract: CHECKBOX_PATTERN,
+ await checkAccessibilitySpec({
+ spec: CHECKBOX_PATTERN,
binding: state.binding,
state: state.id,
facts: state.facts,
diff --git a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx
index 28e31dc4f4..3a30a601c9 100644
--- a/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx
+++ b/packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx
@@ -14,10 +14,9 @@ import {describe, expect, it} from 'vitest';
import {cleanup, render, screen} from '@testing-library/react';
import {
CHECKBOX_PATTERN,
- blockingResults,
+ checkAccessibilitySpec,
createJsdomHarness,
- formatFailures,
- runBinding,
+ expectAccessibilitySpec,
summarize,
type BindingResult,
} from '@astryxdesign/a11y-spec';
@@ -33,9 +32,24 @@ function subjectFor(state: CheckboxBindingRow): Element {
return screen.getByRole(state.facts.role, {hidden: true});
}
-async function runState(state: CheckboxBindingRow): Promise<BindingResult> {
- return runBinding({
- contract: CHECKBOX_PATTERN,
+async function expectState(state: CheckboxBindingRow): Promise<void> {
+ await expectAccessibilitySpec({
+ spec: CHECKBOX_PATTERN,
+ binding: state.binding,
+ state: state.id,
+ facts: state.facts,
+ knownFailures: CHECKBOX_KNOWN_FAILURES,
+ render: () => {
+ render(CHECKBOX_STATE_RENDERS[state.id]());
+ },
+ subject: () => subjectFor(state),
+ cleanup,
+ });
+}
+
+async function checkState(state: CheckboxBindingRow): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: CHECKBOX_PATTERN,
binding: state.binding,
state: state.id,
facts: state.facts,
@@ -55,14 +69,13 @@ describe('the shared checkbox pattern, jsdom lane', () => {
[`${state.binding} [${state.id}]`, state.summary, state] as const,
),
)('%s — %s', async (_id, _summary, state) => {
- const result = await runState(state);
- expect(formatFailures(blockingResults([result]))).toBe('');
+ await expectState(state);
});
it('runs the DOM layer here and reports higher layers as unrun', async () => {
const results: BindingResult[] = [];
for (const state of CHECKBOX_BINDING_STATES) {
- results.push(await runState(state));
+ results.push(await checkState(state));
}
const report = summarize(CHECKBOX_PATTERN, results);
expect(report.counts.pass).toBeGreaterThan(0);
diff --git a/packages/core/src/Switch/__tests__/Switch.a11y.chromium.spec.ts b/packages/core/src/Switch/__tests__/Switch.a11y.chromium.spec.ts
index d4d0d9818a..753b3c5f76 100644
--- a/packages/core/src/Switch/__tests__/Switch.a11y.chromium.spec.ts
+++ b/packages/core/src/Switch/__tests__/Switch.a11y.chromium.spec.ts
@@ -26,7 +26,7 @@ import {
formatFailures,
formatReport,
neverExercised,
- runBinding,
+ checkAccessibilitySpec,
spokenWords,
summarize,
unmatchedKnownFailures,
@@ -91,8 +91,8 @@ async function runState(
cdp: CDPSession,
state: SwitchBindingState,
): Promise<BindingResult> {
- return runBinding({
- contract: SWITCH_PATTERN,
+ return checkAccessibilitySpec({
+ spec: SWITCH_PATTERN,
binding: 'Switch',
state: state.id,
facts: state.facts,
@@ -136,7 +136,7 @@ function namesTheSameLabel(rendered: string, claimed: string): boolean {
/**
* The inventory AST-021 FR2 asks for, checked against the page rather than
- * trusted. It is deliberately NOT part of the shared contract: a wrong entry
+ * trusted. It is deliberately NOT part of the shared spec: a wrong entry
* here is a stale inventory, and reporting it as a WCAG 2.5.3 failure would put
* a metadata typo and a real accessibility defect in the same bucket.
*/
diff --git a/packages/core/src/Switch/__tests__/Switch.a11y.test.tsx b/packages/core/src/Switch/__tests__/Switch.a11y.test.tsx
index 0902705862..e30b8a8eb4 100644
--- a/packages/core/src/Switch/__tests__/Switch.a11y.test.tsx
+++ b/packages/core/src/Switch/__tests__/Switch.a11y.test.tsx
@@ -24,11 +24,10 @@ import {describe, expect, it} from 'vitest';
import {cleanup, fireEvent, render, screen} from '@testing-library/react';
import {
SWITCH_PATTERN,
- blockingResults,
+ checkAccessibilitySpec,
createJsdomHarness,
- formatFailures,
+ expectAccessibilitySpec,
summarize,
- runBinding,
type BindingResult,
} from '@astryxdesign/a11y-spec';
import {Switch, type SwitchProps} from '../Switch';
@@ -71,36 +70,47 @@ function RemotelyToggledSwitch({
);
}
-async function runState(state: SwitchBindingState): Promise<BindingResult> {
- return runBinding({
- contract: SWITCH_PATTERN,
+function renderState(state: SwitchBindingState): void {
+ if (state.arrivesBy === 'controlled-update') {
+ render(
+ <RemotelyToggledSwitch {...state.props} movesTo={state.facts.checked} />,
+ );
+ fireEvent.click(screen.getByRole('button', {name: REMOTE_CONTROL_LABEL}));
+ // A render precondition, not a contract claim: if the owner's change never
+ // reached the control, every expectation would check the wrong state.
+ const control = screen.getByRole('switch', {hidden: true});
+ if ((control as HTMLInputElement).checked !== state.facts.checked) {
+ throw new Error(
+ `rendering "${state.id}" did not reach the declared state: the owner's change left the switch ${(control as HTMLInputElement).checked ? 'on' : 'off'}`,
+ );
+ }
+ } else {
+ render(<ControlledSwitch {...state.props} />);
+ }
+}
+
+async function expectState(state: SwitchBindingState): Promise<void> {
+ await expectAccessibilitySpec({
+ spec: SWITCH_PATTERN,
+ binding: 'Switch',
+ state: state.id,
+ facts: state.facts,
+ knownFailures: SWITCH_KNOWN_FAILURES,
+ render: () => renderState(state),
+ subject: () => screen.getByRole('switch', {hidden: true}),
+ cleanup,
+ });
+}
+
+async function checkState(state: SwitchBindingState): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: SWITCH_PATTERN,
binding: 'Switch',
state: state.id,
facts: state.facts,
knownFailures: SWITCH_KNOWN_FAILURES,
mount: async () => {
- if (state.arrivesBy === 'controlled-update') {
- render(
- <RemotelyToggledSwitch
- {...state.props}
- movesTo={state.facts.checked}
- />,
- );
- fireEvent.click(
- screen.getByRole('button', {name: REMOTE_CONTROL_LABEL}),
- );
- // A mount precondition, not a contract claim: if the owner's change
- // never reached the control, every expectation below would be about a
- // state this binding is not in.
- const control = screen.getByRole('switch', {hidden: true});
- if ((control as HTMLInputElement).checked !== state.facts.checked) {
- throw new Error(
- `mounting "${state.id}" did not reach the declared state: the owner's change left the switch ${(control as HTMLInputElement).checked ? 'on' : 'off'}`,
- );
- }
- } else {
- render(<ControlledSwitch {...state.props} />);
- }
+ renderState(state);
return createJsdomHarness({
subject: screen.getByRole('switch', {hidden: true}),
});
@@ -115,14 +125,13 @@ describe('Switch — the shared switch pattern, jsdom lane', () => {
state => [state.id, state.summary, state] as const,
),
)('%s (%s)', async (_id, _summary, state) => {
- const result = await runState(state);
- expect(formatFailures(blockingResults([result]))).toBe('');
+ await expectState(state);
});
it('runs the DOM layer here and reports the higher layers as unrun', async () => {
const results: BindingResult[] = [];
for (const state of SWITCH_BINDING_STATES) {
- results.push(await runState(state));
+ results.push(await checkState(state));
}
const report = summarize(SWITCH_PATTERN, results);