Skip to content

Accessibility Testing

Automate a11y checks with axe, test keyboard flow, and verify ARIA semantics.

What you'll learn

  • Why accessibility testing is a first-class testing concern
  • Running axe automated checks with jest-axe and @vitest/browser
  • Testing keyboard navigation and focus management
  • Verifying ARIA roles, labels, and color contrast

Concept

Accessibility Is Testing

An inaccessible UI is a broken UI — for screen reader users, keyboard users, and anyone on a slow or small device. Accessibility (a11y) testing automates the checks that catch the most common violations: missing labels, insufficient contrast, duplicate ids, invalid ARIA. Like any other bug, an a11y bug is cheapest to fix when caught immediately in development.

Automated Checks with axe

axe-core is a rules engine that scans the DOM for a11y violations. jest-axe and @axe-core/playwright wrap it for tests. After rendering a component, run expect(await axe(container)).toHaveNoViolations() and the test fails if axe finds any issue. Automated checks catch roughly 30–40% of WCAG issues — they are necessary but not sufficient, so combine them with manual and keyboard tests.

Keyboard Testing

Many users navigate by keyboard alone. Test that every interactive element is reachable with Tab, that focus order is logical, that Enter and Space activate buttons, and that modals trap focus and return it on close. Use Testing Library's userEvent.tab() and userEvent.keyboard to drive these flows. A component that works only with the mouse is broken for keyboard users.

ARIA and Contrast

Assert that interactive elements have accessible names (getByRole enforces this), that images have alt text (or are marked decorative), and that form fields have associated labels. Check color contrast with axe or a tool like @axe-core/playwright's contrast rule. These checks are fast to automate and catch the violations that most often lead to real-world exclusion.

In Practice

Integrate axe into every component test so a11y violations fail the build immediately, not in a separate audit weeks later. Run a broader axe scan against rendered pages in E2E tests to catch issues that appear only when components compose. Beyond automation, periodically navigate your app with a screen reader (VoiceOver, NVDA) and with the keyboard alone — automation cannot detect confusing reading order, unlabeled icon buttons that a sighted user infers, or focus traps that break flow. Treat accessibility bugs with the same urgency as functional bugs: file them, fix them, and add a regression test. Building accessible components from the start (semantic HTML, labeled inputs, sufficient contrast) is far cheaper than retrofitting, and testing keeps them accessible as the UI evolves.

Example

              import { describe, it, expect } from "vitest";
import { render } from "@testing-library/react";
import { axe } from "vitest-axe";
import { LoginForm } from "./LoginForm";

describe("LoginForm accessibility", () => {
  it("has no a11y violations", async () => {
    const { container } = render(<LoginForm />);
    const results = await axe(container);
    expect(results.violations).toEqual([]);
  });

  it("submits when pressing Enter in the password field", async () => {
    const user = userEvent.setup();
    render(<LoginForm />);
    await user.type(screen.getByLabelText(/password/i), "secret{Enter}");
    expect(screen.getByText("Welcome")).toBeInTheDocument();
  });
});
            

axe scans the rendered DOM for violations like missing labels and low contrast. The keyboard test verifies a real user can submit without a mouse.

Try it

  • Color Tool

    Check foreground/background contrast ratios manually.

  • Code Diff

    Review the DOM changes that fix a11y violations.

Common mistakes

The mistake

Treating axe as a complete a11y audit

The fix

axe catches only automated-checkable issues. Always add keyboard tests and screen-reader spot checks; many WCAG failures are not automatable.

The mistake

Adding aria-label to elements that already have visible text

The fix

Prefer visible labels. Redundant aria-labels can override the accessible name and confuse screen readers. Use getByRole to confirm the name.

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors