TestingBeginner15 min

Add Automated Accessibility Testing to a Next.js App

Automated scans catch roughly a third of real accessibility issues — but that third is worth catching on every pull request, not just when someone remembers to check.

Prerequisites

A Next.js project (App Router) you can run locally
Node.js and a package manager (npm, pnpm, or yarn) installed
Comfort running a test suite from the command line

Setup

Install Playwright and the axe integration as dev dependencies, then install Playwright's browser binaries.

Shell

1pnpm add -D @playwright/test @axe-core/playwright2pnpm exec playwright install --with-deps chromium

Step 1: Write a basic Playwright test

Create a test file that visits a real page in your app. This is the page an accessibility scan will run against.

e2e/accessibility.spec.ts

TypeScript

1import { expect, test } from "@playwright/test";2 3test("homepage loads", async ({ page }) => {4  await page.goto("/");5  await expect(page).toHaveTitle(/./);6});

Step 2: Add an AxeBuilder scan

Import AxeBuilder, run it against the loaded page, and assert there are zero violations. Scoping to wcag2a/wcag2aa/best-practice keeps the scan focused on real, actionable rules.

e2e/accessibility.spec.ts

TypeScript

1import AxeBuilder from "@axe-core/playwright";2import { expect, test } from "@playwright/test";3 4test("homepage has no automatically detectable accessibility violations", async ({ page }) => {5  await page.goto("/");6 7  const results = await new AxeBuilder({ page })8    .withTags(["wcag2a", "wcag2aa", "best-practice"])9    .analyze();10 11  expect(results.violations).toEqual([]);12});

Step 3: Run it and read the output

Run the test. A passing scan prints nothing unusual; a failing one lists each violation with the specific element and rule that failed, which is usually enough to fix it directly.

Shell

1pnpm exec playwright test e2e/accessibility.spec.ts

Validation

Run the suite once against your unmodified page — it should pass. Then intentionally break something real (remove an image's alt text, or drop a form label) and run it again — the same test should now fail and name the specific violation. If both of those are true, the scan is doing its job.

Next steps

Add a scan for every major page template, not just one — a single passing scan doesn't cover pages with different components
Wire the test into CI so an accessibility regression fails the build instead of shipping
Pair automated scans with a real manual pass — automated tools catch roughly a third of real issues; see the Accessibility Checklist playbook for what to check by hand

Browse all tutorials Plan a similar build with BuildPath

Step 1: Write a basic Playwright test

Create a test file that visits a real page in your app. This is the page an accessibility scan will run against.

e2e/accessibility.spec.ts

TypeScript

1import { expect, test } from "@playwright/test";2 3test("homepage loads", async ({ page }) => {4  await page.goto("/");5  await expect(page).toHaveTitle(/./);6});

Step 2: Add an AxeBuilder scan

Import AxeBuilder, run it against the loaded page, and assert there are zero violations. Scoping to wcag2a/wcag2aa/best-practice keeps the scan focused on real, actionable rules.

e2e/accessibility.spec.ts

TypeScript

1import AxeBuilder from "@axe-core/playwright";2import { expect, test } from "@playwright/test";3 4test("homepage has no automatically detectable accessibility violations", async ({ page }) => {5  await page.goto("/");6 7  const results = await new AxeBuilder({ page })8    .withTags(["wcag2a", "wcag2aa", "best-practice"])9    .analyze();10 11  expect(results.violations).toEqual([]);12});

Next steps

Add a scan for every major page template, not just one — a single passing scan doesn't cover pages with different components

Wire the test into CI so an accessibility regression fails the build instead of shipping

Pair automated scans with a real manual pass — automated tools catch roughly a third of real issues; see the Accessibility Checklist playbook for what to check by hand