Skip to content

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

TypeScript

test(a11y): correct spinbutton contract fixtures (#6758)

Cindy Zhang57751544519f
diff --git a/internal/a11y-spec/src/patterns/spinbutton.chromium.spec.ts b/internal/a11y-spec/src/patterns/spinbutton.chromium.spec.ts
index 6ca4432840..d72c168086 100644
--- a/internal/a11y-spec/src/patterns/spinbutton.chromium.spec.ts
+++ b/internal/a11y-spec/src/patterns/spinbutton.chromium.spec.ts
@@ -1,9 +1,14 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-/** Chromium positive and mutation proof for the shared Spinbutton contract. */
+/** Chromium positive, exact-debt, and mutation proof for the shared Spinbutton contract. */
import {expect, test, type Page} from '@playwright/test';
-import {checkAccessibilitySpec, requiredLayers} from '../index';
+import {
+ checkAccessibilitySpec,
+ requiredLayers,
+ unmatchedKnownFailures,
+ type BindingResult,
+} from '../index';
import {CHROMIUM_OBSERVES, createChromiumHarness} from '../harness/chromium';
import {SPINBUTTON_PATTERN} from './spinbutton';
import {
@@ -12,6 +17,7 @@ import {
SPINBUTTON_SUBJECT_SELECTOR,
spinbuttonFixture,
} from './spinbutton.fixtures';
+import {SPINBUTTON_FIXTURE_KNOWN_FAILURES} from './spinbutton.known-failures';
async function run(page: Page, id: string, only?: readonly string[]) {
const fixture = spinbuttonFixture(id);
@@ -22,6 +28,7 @@ async function run(page: Page, id: string, only?: readonly string[]) {
state: id,
facts: fixture.facts,
only,
+ knownFailures: SPINBUTTON_FIXTURE_KNOWN_FAILURES,
mount: async () => {
await page.setContent(fixture.html);
return createChromiumHarness({
@@ -34,7 +41,7 @@ async function run(page: Page, id: string, only?: readonly string[]) {
}
for (const expectation of SPINBUTTON_PATTERN.expectations) {
- test(`${expectation.id} has Chromium coverage`, async ({page}) => {
+ test(`${expectation.id} has Chromium evidence`, async ({page}) => {
expect(
requiredLayers(expectation).every(layer =>
CHROMIUM_OBSERVES.includes(layer),
@@ -48,7 +55,13 @@ for (const expectation of SPINBUTTON_PATTERN.expectations) {
throw new Error(`no conforming fixture exercises ${expectation.id}`);
}
const result = await run(page, conforming, [expectation.id]);
- expect(result.results[0]?.status).toBe('pass');
+ const recorded = SPINBUTTON_FIXTURE_KNOWN_FAILURES.some(
+ failure =>
+ failure.expectation === expectation.id &&
+ failure.binding === 'fixture' &&
+ failure.state === conforming,
+ );
+ expect(result.results[0]?.status).toBe(recorded ? 'known-failure' : 'pass');
});
for (const mutation of SPINBUTTON_MUTATIONS[expectation.id] ?? []) {
@@ -59,3 +72,15 @@ for (const expectation of SPINBUTTON_PATTERN.expectations) {
});
}
}
+
+test('every fixture known failure matches exactly one result', async ({
+ page,
+}) => {
+ const results: BindingResult[] = [];
+ for (const failure of SPINBUTTON_FIXTURE_KNOWN_FAILURES) {
+ results.push(await run(page, failure.state, [failure.expectation]));
+ }
+ expect(
+ unmatchedKnownFailures(SPINBUTTON_FIXTURE_KNOWN_FAILURES, results),
+ ).toEqual([]);
+});
diff --git a/internal/a11y-spec/src/patterns/spinbutton.fixtures.ts b/internal/a11y-spec/src/patterns/spinbutton.fixtures.ts
index 8918bfbb54..f36c65dc66 100644
--- a/internal/a11y-spec/src/patterns/spinbutton.fixtures.ts
+++ b/internal/a11y-spec/src/patterns/spinbutton.fixtures.ts
@@ -34,6 +34,7 @@ interface Options {
readonly role?: string;
readonly label?: boolean;
readonly value?: number | null;
+ readonly displayValue?: string | null;
readonly min?: number | null;
readonly max?: number | null;
readonly valueText?: string | null;
@@ -47,6 +48,12 @@ interface Options {
function html(options: Options = {}): string {
const value = options.value === undefined ? 5 : options.value;
+ const displayValue =
+ options.displayValue === undefined
+ ? value == null
+ ? null
+ : String(value)
+ : options.displayValue;
const min = options.min === undefined ? 1 : options.min;
const max = options.max === undefined ? 9 : options.max;
const valueText = options.valueText === undefined ? null : options.valueText;
@@ -56,12 +63,13 @@ function html(options: Options = {}): string {
<button type="button">Before</button>
${label ? '<label for="amount">Quantity</label>' : ''}
<input data-a11y-subject id="amount" type="text" role="${role}"
- ${value == null ? '' : `value="${value}" aria-valuenow="${value}"`}
+ ${displayValue == null ? '' : `value="${displayValue}"`}
+ ${value == null ? '' : `aria-valuenow="${value}"`}
${min == null ? '' : `aria-valuemin="${min}"`}
${max == null ? '' : `aria-valuemax="${max}"`}
${valueText == null ? '' : `aria-valuetext="${valueText}"`}
${options.disabled ? 'disabled' : ''}
- ${options.readOnly ? 'readonly' : ''}
+ ${options.readOnly ? 'readonly aria-readonly="true"' : ''}
${options.tabIndex == null ? '' : `tabindex="${options.tabIndex}"`}
onkeydown="
if (event.key === 'Tab' && ${options.trapTab ? 'true' : 'false'}) event.preventDefault();
@@ -83,7 +91,7 @@ export const SPINBUTTON_FIXTURES: readonly SpinbuttonFixture[] = [
id: 'conforming-formatted',
summary: 'a formatted spinbutton value',
facts: facts({valueText: '5 GB', stepUpValue: null, stepDownValue: null}),
- html: html({valueText: '5 GB'}),
+ html: html({displayValue: '5 GB', valueText: '5 GB'}),
},
{
id: 'conforming-empty',
@@ -160,7 +168,7 @@ export const SPINBUTTON_FIXTURES: readonly SpinbuttonFixture[] = [
id: 'violating-value-text',
summary: 'incorrect formatted value text',
facts: facts({valueText: '5 GB', stepUpValue: null, stepDownValue: null}),
- html: html({valueText: 'five'}),
+ html: html({displayValue: 'five', valueText: 'five'}),
},
{
id: 'violating-disabled',
diff --git a/internal/a11y-spec/src/patterns/spinbutton.jsdom.test.ts b/internal/a11y-spec/src/patterns/spinbutton.jsdom.test.ts
index 75ca677137..908a6d5a84 100644
--- a/internal/a11y-spec/src/patterns/spinbutton.jsdom.test.ts
+++ b/internal/a11y-spec/src/patterns/spinbutton.jsdom.test.ts
@@ -36,6 +36,15 @@ async function run(id: string) {
});
}
+function inputFor(id: string): HTMLInputElement {
+ document.body.innerHTML = spinbuttonFixture(id).html;
+ const subject = document.querySelector(SPINBUTTON_SUBJECT_SELECTOR);
+ if (!(subject instanceof HTMLInputElement)) {
+ throw new Error(`fixture "${id}" does not render an input subject`);
+ }
+ return subject;
+}
+
const observableHere = SPINBUTTON_PATTERN.expectations.filter(expectation =>
requiredLayers(expectation).every(layer => JSDOM_OBSERVES.includes(layer)),
);
@@ -66,6 +75,38 @@ describe('Spinbutton contract — completeness', () => {
});
});
+describe('Spinbutton contract — fixture semantics', () => {
+ it('renders the formatted value text that the fixture declares', () => {
+ const fixture = spinbuttonFixture('conforming-formatted');
+ const subject = inputFor(fixture.id);
+ expect(subject.value).toBe(fixture.facts.valueText);
+ expect(subject.getAttribute('aria-valuetext')).toBe(
+ fixture.facts.valueText,
+ );
+ });
+
+ it('declares the read-only state through aria-readonly', () => {
+ const subject = inputFor('conforming-readonly');
+ expect(subject.readOnly).toBe(true);
+ expect(subject.getAttribute('aria-readonly')).toBe('true');
+ });
+
+ it('does not apply the read-only expectation to a disabled state', () => {
+ const expectation = SPINBUTTON_PATTERN.expectations.find(
+ candidate => candidate.id === 'spinbutton.readonly.exposed',
+ );
+ if (expectation == null) {
+ throw new Error('Spinbutton contract has no read-only expectation');
+ }
+ expect(
+ expectation.appliesWhen.test({
+ ...spinbuttonFixture('conforming-readonly').facts,
+ disabled: true,
+ }),
+ ).toBe(false);
+ });
+});
+
describe('Spinbutton contract — jsdom evidence boundary', () => {
it('runs DOM expectations and reports browser-owned layers as unrun', async () => {
const result = await run('conforming-empty');
diff --git a/internal/a11y-spec/src/patterns/spinbutton.known-failures.ts b/internal/a11y-spec/src/patterns/spinbutton.known-failures.ts
new file mode 100644
index 0000000000..e90e1948ad
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/spinbutton.known-failures.ts
@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file spinbutton.known-failures.ts
+ * @input Uses KnownFailure from the shared accessibility-spec runner
+ * @output SPINBUTTON_FIXTURE_KNOWN_FAILURES — exact public-safe fixture debt
+ * @position AST-021 FR8–FR10 records for outcomes a real browser still fails.
+ */
+
+import type {KnownFailure} from '../check';
+
+export const SPINBUTTON_FIXTURE_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+ {
+ expectation: 'spinbutton.readonly.exposed',
+ binding: 'fixture',
+ state: 'conforming-readonly',
+ evidenceLayer: 'accessibility-tree',
+ failureEquals:
+ 'the binding declares this spinbutton read-only, but the browser does not expose read-only state',
+ standardsReference: 'WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
+ userImpact:
+ 'An accessibility consumer encounters a read-only spinbutton without a programmatically exposed read-only state and may expect that its value can still be edited.',
+ reason:
+ 'Chromium 149 omits the read-only accessibility-tree property for a spinbutton that carries both native readonly and aria-readonly. This record preserves the required outcome as visible debt without weakening the contract.',
+ },
+];
diff --git a/internal/a11y-spec/src/patterns/spinbutton.ts b/internal/a11y-spec/src/patterns/spinbutton.ts
index 0aa7486e77..a438928336 100644
--- a/internal/a11y-spec/src/patterns/spinbutton.ts
+++ b/internal/a11y-spec/src/patterns/spinbutton.ts
@@ -259,8 +259,8 @@ export const SPINBUTTON_PATTERN: PatternContract<SpinbuttonStateFacts> =
sources: [WCAG_4_1_2],
covers: ['4.1.2-name-role-value'],
appliesWhen: {
- condition: 'the binding declares this state read-only',
- test: facts => facts.readOnly,
+ condition: 'the binding declares this state read-only and available',
+ test: facts => facts.readOnly && !facts.disabled,
},
evidenceLayer: 'accessibility-tree',
enforcement: 'required',
diff --git a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts
index 0307486cb5..98c2ef8b9d 100644
--- a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts
+++ b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts
@@ -10,6 +10,7 @@ import {
formatFailures,
neverExercised,
summarize,
+ unmatchedKnownFailures,
type BindingResult,
} from '@astryxdesign/a11y-spec';
import {
@@ -21,6 +22,7 @@ import {
serveStorybook,
type StaticServer,
} from '@astryxdesign/a11y-spec/storybook';
+import {NUMBER_INPUT_KNOWN_FAILURES} from './NumberInput.a11y.known-failures';
import {
NUMBER_INPUT_A11Y_STATES,
type NumberInputA11yRow,
@@ -57,6 +59,7 @@ async function runState(
binding: 'NumberInput',
state: state.id,
facts: state.facts,
+ knownFailures: NUMBER_INPUT_KNOWN_FAILURES,
mount: async () => {
await mount(page, state);
return createChromiumHarness({
@@ -78,6 +81,27 @@ test('every expectation is exercised by at least one NumberInput state', async (
results.push(await runState(page, cdp, state));
}
expect(neverExercised(results)).toEqual([]);
+ expect(unmatchedKnownFailures(NUMBER_INPUT_KNOWN_FAILURES, results)).toEqual(
+ [],
+ );
+});
+
+test('the Chromium read-only omission remains exact visible debt', async ({
+ page,
+}) => {
+ const state = NUMBER_INPUT_A11Y_STATES.find(
+ candidate => candidate.id === 'read-only',
+ );
+ if (state == null) {
+ throw new Error('missing NumberInput accessibility state: read-only');
+ }
+ const cdp = await page.context().newCDPSession(page);
+ const result = await runState(page, cdp, state);
+ const readOnly = result.results.find(
+ candidate => candidate.expectation === 'spinbutton.readonly.exposed',
+ );
+ expect(readOnly?.status).toBe('known-failure');
+ expect(readOnly?.knownFailure).toBe(NUMBER_INPUT_KNOWN_FAILURES[0]);
});
for (const state of NUMBER_INPUT_A11Y_STATES) {
@@ -87,5 +111,6 @@ for (const state of NUMBER_INPUT_A11Y_STATES) {
const report = summarize(SPINBUTTON_PATTERN, [result]);
expect(formatFailures(blockingResults([result]))).toBe('');
expect(report.unrunLayers).toEqual([]);
+ expect(report.counts.unexpectedPass).toBe(0);
});
}
diff --git a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.known-failures.ts b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.known-failures.ts
new file mode 100644
index 0000000000..c4e4229903
--- /dev/null
+++ b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.known-failures.ts
@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file NumberInput.a11y.known-failures.ts
+ * @input Uses KnownFailure from @astryxdesign/a11y-spec
+ * @output NUMBER_INPUT_KNOWN_FAILURES — exact public-safe NumberInput debt
+ * @position AST-021 FR8–FR10 records; operational ownership stays outside public source.
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const NUMBER_INPUT_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+ {
+ expectation: 'spinbutton.readonly.exposed',
+ binding: 'NumberInput',
+ state: 'read-only',
+ evidenceLayer: 'accessibility-tree',
+ failureEquals:
+ 'the binding declares this spinbutton read-only, but the browser does not expose read-only state',
+ standardsReference: 'WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
+ userImpact:
+ 'An accessibility consumer encounters a read-only NumberInput without a programmatically exposed read-only state and may expect that its value can still be edited.',
+ reason:
+ 'Chromium 149 omits the read-only accessibility-tree property for the native read-only text input promoted to spinbutton semantics. Adding aria-readonly produces the same tree, so this test-contract change records the existing behavior without changing the component.',
+ },
+];
diff --git a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.states.ts b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.states.ts
index 2bb8b5bed8..4aa9883cbb 100644
--- a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.states.ts
+++ b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.states.ts
@@ -69,9 +69,8 @@ export const NUMBER_INPUT_A11Y_STATES = [
},
{
id: 'disabled-with-message',
- summary:
- 'an unavailable read-only spinbutton kept focusable for its reason',
- facts: facts({disabled: true, readOnly: true}),
+ summary: 'an unavailable spinbutton kept focusable for its reason',
+ facts: facts({disabled: true}),
storyId: story('disabled-with-message'),
},
{
diff --git a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.test.tsx b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.test.tsx
index 2bb3bc7073..3e967f45e4 100644
--- a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.test.tsx
+++ b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.test.tsx
@@ -44,6 +44,24 @@ async function checkState(state: NumberInputA11yRow): Promise<BindingResult> {
});
}
+function stateFor(id: NumberInputA11yRow['id']): NumberInputA11yRow {
+ const state = NUMBER_INPUT_A11Y_STATES.find(candidate => candidate.id === id);
+ if (state == null) {
+ throw new Error(`NumberInput accessibility inventory has no state "${id}"`);
+ }
+ return state;
+}
+
+function expectationFor(id: string) {
+ const expectation = SPINBUTTON_PATTERN.expectations.find(
+ row => row.id === id,
+ );
+ if (expectation == null) {
+ throw new Error(`Spinbutton contract has no expectation "${id}"`);
+ }
+ return expectation;
+}
+
describe('the shared Spinbutton pattern, jsdom lane', () => {
it.each(
NUMBER_INPUT_A11Y_STATES.map(
@@ -63,6 +81,44 @@ describe('the shared Spinbutton pattern, jsdom lane', () => {
});
});
+ it('preserves formatted and disabled-reason coverage without treating disabled as read-only', async () => {
+ const formatted = stateFor('formatted-value');
+ const disabledWithMessage = stateFor('disabled-with-message');
+
+ expect(
+ expectationFor('spinbutton.value-text.exposed').appliesWhen.test(
+ formatted.facts,
+ ),
+ ).toBe(true);
+ expect(disabledWithMessage.facts).toMatchObject({
+ disabled: true,
+ readOnly: false,
+ focusable: true,
+ });
+ expect(
+ [
+ 'spinbutton.disabled.exposed',
+ 'spinbutton.keyboard.reachable-and-escapable',
+ ].map(id =>
+ expectationFor(id).appliesWhen.test(disabledWithMessage.facts),
+ ),
+ ).toEqual([true, true]);
+ expect(
+ expectationFor('spinbutton.readonly.exposed').appliesWhen.test(
+ disabledWithMessage.facts,
+ ),
+ ).toBe(false);
+
+ const result = await checkState(disabledWithMessage);
+ const status = (id: string) =>
+ result.results.find(row => row.expectation === id)?.status;
+ expect([
+ status('spinbutton.disabled.exposed'),
+ status('spinbutton.keyboard.reachable-and-escapable'),
+ status('spinbutton.readonly.exposed'),
+ ]).toEqual(['unrun', 'unrun', 'not-applicable']);
+ });
+
it('runs DOM expectations and reports browser-owned layers as unrun', async () => {
const results: BindingResult[] = [];
for (const state of NUMBER_INPUT_A11Y_STATES) {