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.mdindex 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 failuresA known failure names one expectation, one binding, one state, one evidencediff --git a/internal/a11y-spec/src/run.test.ts b/internal/a11y-spec/src/check.test.tssimilarity index 97%rename from internal/a11y-spec/src/run.test.tsrename to internal/a11y-spec/src/check.test.tsindex 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.tssimilarity index 95%rename from internal/a11y-spec/src/run.tsrename to internal/a11y-spec/src/check.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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.tsxindex 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.tsindex 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.tsxindex 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);