Accessibility testing
Testing accessibility in layers
How semantic assertions, keyboard tests, axe, contrast, responsive review, reduced motion, RTL, and manual smoke tests fit without overstating coverage.
By Gummy UI · Published
Test the semantic contract
The first layer asks whether the rendered control has the right element, role, name, value, relationship, and state. Testing Library queries encourage the suite to interact through those public signals. A label test is stronger when it finds the input by name; a dialog test is stronger when it observes the named surface and focus path.
These assertions are close to the component’s source contract and run quickly across many changes. They can still miss browser layout, platform accessibility mappings, or an interaction that depends on real rendering. Passing unit tests are necessary evidence, not a complete accessibility claim.
Use axe for representative trees
Axe examines representative rendered states for detectable rule violations. Gummy UI uses it on groups of canonical components, including open overlays and composed forms. The test environment disables colour contrast because jsdom does not provide the rendered pixels needed for that rule; selected stable token pairs are checked separately.
That separation should remain visible in reports. “No axe violations in this fixture” is precise. “The component is accessible everywhere” is not. Different states, consumer composition, browser behavior, language, and assistive technology can introduce issues beyond the fixture.
Exercise input and environment
Keyboard tests cover activation, arrow navigation, Home and End behavior, Escape dismissal, and focus restoration where those contracts apply. Pointer and native change paths matter as well, especially for forms and direct-manipulation components. Touch target size and mobile reflow need rendered measurement rather than a DOM-only assertion.
Theme, zoom, RTL, and reduced motion add environmental coverage. Logical CSS can be inspected in source, but mixed-direction content still needs a browser. A reduced-motion rule can be present while an active transform remains. Layered testing is designed to catch these different failure modes.
Record manual evidence honestly
Screen-reader smoke tests should identify the platform, browser, assistive technology, component state, commands, and observed output. Zoom and reflow records should include viewport and scale. Findings, fixes, and re-tests belong beside the result so a later change can be compared with the same path.
The current public application includes automated behavior, axe, contrast, registry, and selected browser audit records. The master specification still keeps full release accessibility evidence open. That status makes the remaining work actionable and avoids turning a partial automated suite into a promise it cannot support.