DEV Community: Vitaly Skadorva

Accessibility Testing: Best Practices

Vitaly Skadorva — Mon, 27 Apr 2026 03:08:19 +0000

Accessibility testing requires more than an automated scanner. A scanner catches roughly 30-50% of WCAG issues. The rest requires manual testing with a keyboard, a screen reader, and a process that covers every state of the application.

This guide is tool-agnostic. Whether the team uses Cypress, Playwright, Selenium, or another framework, the practices apply. Tool-specific implementation guides are linked at the end.

The compliance landscape has shifted. Over 5,000 accessibility lawsuits were filed in the US in 2025, and nearly half targeted companies that had already been sued before. The European Accessibility Act started enforcement in June 2025. For QA teams, accessibility testing is no longer optional in most organizations. It is a compliance requirement with real consequences.

Start with the keyboard

Before running a scanner, unplug the mouse.

Tab through every interactive element on the page. Press Enter and Space on buttons and links. Open dropdowns with the keyboard. Navigate modals. Complete the same user flows tested functionally: sign up, search, checkout, submit a form.

Four things to verify. Can every interactive element be reached by tabbing? Is there a visible focus indicator? Can each element be activated with Enter or Space? Can the user leave every component without getting trapped?

Keyboard-only testing and screen reader testing are different tests. A screen reader might activate an element with Enter, giving a false sense of keyboard accessibility. Without the screen reader running, that same Enter keypress might do nothing. Test both separately.

Keyboard testing accounts for about 10% of a full accessibility evaluation, according to Deque's methodology. It should always come first because it answers the most basic question: can someone who doesn't use a mouse operate this page at all?

Test at 200% zoom

WCAG 1.4.4 requires that text can be resized to 200% without losing content or functionality. WCAG 1.4.10 goes further: at 400% zoom (or equivalently, a 320px-wide viewport), there should be no horizontal scrolling for vertical content. These criteria matter for every user with low vision who enlarges their screen rather than using a full-screen magnifier.

The test takes seconds. Open the page in Chrome, press Ctrl+Plus (Cmd+Plus on Mac) until 200%, and try to complete the main user flow. Then set the viewport to 320px wide in DevTools and check for horizontal scrollbars. Fixed-width containers and absolute positioning are the usual culprits.

Run this check alongside keyboard testing on every new feature. It catches layout problems that no automated scanner reports.

Pick two screen readers and learn the basics

The goal is to complete the same user flows tested functionally with a screen reader running.

The two most common pairings are NVDA with Chrome on Windows and VoiceOver with Safari on macOS. NVDA is free. VoiceOver ships with every Mac.

NVDA essentials: Insert+Space toggles between browse and focus mode. Tab moves between focusable elements. The down arrow reads the next item. H jumps between headings. The screen reader announces element roles, names, and states during navigation.

VoiceOver essentials: Cmd+F5 turns it on. VO+Right Arrow (VO is Ctrl+Option) moves to the next element. VO+Space activates an element. Rotor (VO+U) navigates by headings, links, or landmarks.

Marcy Sutton, who built the Testing Accessibility workshop series and worked on axe-core at Deque, makes an important point: the learning curve is steep, and without a disability, the tester's experience will differ from users with disabilities. That is expected. The purpose is to catch broken announcements and missing labels, not to simulate a disabled person's experience. The purpose is to catch engineering failures.

Automate what automation can actually catch

Automated scanners like axe-core and Lighthouse are good at finding missing alt text, broken ARIA references, contrast ratio failures, and missing form labels. They are fast and consistent. They belong in the CI pipeline on every pull request.

They cannot tell whether alt text is meaningful. They cannot judge whether the tab order makes sense. They cannot hear what a screen reader announces. They cannot complete a multi-step form and check whether error messages are accessible.

The value of automation is coverage. Hundreds of pages can be scanned in minutes. No human can match that. But a passing automated scan does not mean the page is accessible. It means the page passed the checks that can be automated. Treat it as a floor, not a ceiling.

Deque's 360-degree methodology puts it this way: use automated testing for breadth and manual testing for depth. Run the scanner on everything. Do keyboard and screen reader testing on the pages that matter most.

ARIA misuse is a common problem. WebAIM's annual analysis found that pages using ARIA attributes averaged more than double the accessibility errors of pages without ARIA. Adding role or aria-label to elements that don't need them creates problems that screen reader users have to work around. Use native HTML elements first. A <button> does not need role="button". A <label> does not need aria-label. Reach for ARIA only when HTML cannot express what is needed.

Test after every state change

A page can have zero violations on load and introduce five the moment a user triggers a form validation error. The error messages might lack aria-live regions, so a screen reader never announces them. The invalid fields might be missing aria-invalid and aria-describedby, so a screen reader user does not know which field has the problem or what the error says.

Modals are another common source. The modal itself might be accessible, but when it opens, does focus move into it? When it closes, does focus return to the trigger?

Run accessibility checks after every meaningful interaction. Page load, modal open, modal close, form submission with errors, search results rendering, accordion expand, and empty state. Each creates a new DOM. Each can introduce new violations.

Know what WCAG 2.2 added

WCAG 2.2 landed in October 2023 and added nine new success criteria. The ones teams miss most often:

Focus not obscured (2.4.11) requires that the keyboard focus indicator is not hidden behind sticky headers, cookie banners, or chat widgets. Focus appearance (2.4.13) requires the indicator to have a minimum size and contrast. Dragging movements (2.5.7) requires that any action performable by dragging has a non-dragging alternative. Target size minimum (2.5.8) sets 24x24 CSS pixels as the floor for interactive elements.

Two criteria affect forms directly. Redundant entry (3.3.7) states that users should not have to re-enter information they have already provided in the same process. Consistent help (3.2.6) requires that help mechanisms appear in the same relative location across pages.

Add these to the test checklist as a separate pass. Most automated scanners do not cover them yet. The dragging and focus obscured checks in particular require a human with a keyboard.

Test authentication flows

OTP and 2FA implementations frequently create accessibility barriers, as documented by Sheri Byrne-Haber, an assistive technology user and accessibility consultant.

OTP codes often expire in 30 to 60 seconds. A screen reader user navigating to the input field, reading the label, and typing six digits can easily run out of time. WCAG 2.1 Success Criterion 2.2.1 requires that users can turn off, adjust, or extend time limits unless the limit is essential. A 30-second OTP expiry is rarely essential.

The input field itself is where many implementations break. Multiple individual character boxes are difficult to navigate with a screen reader or keyboard. A single text input with inputmode="numeric" and autocomplete="one-time-code" is more accessible and lets browsers offer autofill from SMS on supported devices. Add a descriptive aria-label like "Enter the 6-digit code sent to your phone" so screen reader users know what is expected.

State changes during authentication need ARIA live regions. When a code is sent, when it expires, and when submission fails. Use aria-live="polite" for informational messages and aria-live="assertive" only for errors that need immediate attention.

If the system recommends an authenticator app, test it with VoiceOver on iOS and TalkBack on Android. Many authenticator apps have small tap targets and poor contrast on countdown timers. WCAG 2.5.5 sets the minimum tap target at 44x44 pixels.

The long-term direction is passkeys and OAuth. Passkeys based on FIDO2/WebAuthn replace typed codes with biometric or device-based authentication. OAuth reduces the number of login forms a user has to navigate. Both reduce friction for users with motor and cognitive disabilities.

Do not stop at the login page. Account recovery flows often have the same problems with worse fallbacks. Test those too.

Consider cognitive disabilities

Accessibility testing often focuses on screen readers and keyboard navigation, targeting blind and motor-impaired users. But cognitive disabilities cover more ground than any other category. A person with ADHD who loses focus when an animation loops, or a person with dyslexia who cannot parse a dense error message, faces real barriers.

WCAG has been slow to address this group, but WCAG 2.2's redundant entry and consistent help criteria are a start. Cognitive barriers are things automation cannot flag.

Check that error messages say what went wrong and what to do about it, in plain language. Check that navigation is consistent across pages. Check that animations can be paused or disabled (WCAG 2.3.3 and the prefers-reduced-motion media query). Check that time limits allow extension. Look at the reading level. If a critical instruction requires a university reading level to parse, it is a barrier.

An error that says "invalid input format" fails the user. "Please enter your phone number as 555-555-5555" works. Add a "plain language" pass to accessibility reviews.

Include people with disabilities in testing

Marcy Sutton recommends paid user testing with organizations like Fable Tech Labs and Access Works. These services connect teams with people who use assistive technology daily. They test the product and report what works and what does not.

This is the step most teams skip. It is also the one that permanently changes how a team thinks about accessibility. An automated scan reports that a button is missing a label. A user testing session shows a person unable to complete a task the team thought was simple. The second one gets the budget allocated.

If a full user testing engagement is not feasible, start smaller. Invite a screen reader user to walk through the product for an hour. Record the session. Share it with the team. One session is worth more than a hundred automated scan reports.

Build accessibility into the definition of done

Marcy Sutton's Testing Accessibility framework makes the case that accessibility needs to be part of the definition of done for design and development, alongside QA. If it is only the QA team's responsibility, it arrives too late and costs too much to fix.

For designers, this means contrast checks for color tokens and focus-state designs for every interactive component.

For developers, it means semantic HTML first. A <button> instead of a <div onclick>. A <label> associated with its input. ARIA attributes only when native elements cannot do the job.

For QA, it means a keyboard walkthrough on every new feature and a screen reader pass on the most critical flows. An automated scan in CI that fails the build on critical violations covers the rest.

When all three roles share the responsibility, accessibility issues surface earlier and cost less to fix.

Document what gets tested and how

Without a written plan, accessibility testing depends on individual motivation. When that person leaves the team, the practice leaves with them.

A lightweight accessibility test plan covers which pages get manual testing (prioritized by traffic and risk) and which user flows get screen reader passes. It should also specify how often each type of testing runs and who is responsible.

The format does not matter. A wiki page, a markdown file in the repo, a Notion document. What matters is that it exists and someone updates it when the product changes.

Do not forget mobile

Mobile accessibility testing is its own discipline.

VoiceOver on iOS and TalkBack on Android are the two screen readers to use. The interaction model differs from the desktop. On mobile, users swipe left and right to move between elements. Double-tap activates. There is no Tab key.

WCAG 2.2 sets the minimum touch target size at 24x24 CSS pixels. That sounds small, but icon buttons and close buttons on mobile frequently fail this. A 16x16 icon with no padding is unusable for someone with a motor impairment.

The other common mobile failure: content that works with a mouse hover but has no equivalent on touch. Tooltips triggered by hover disappear entirely on mobile. If the tooltip contains information the user needs, that information is gone.

Test critical flows on a real device with the screen reader running. Emulators do not always behave the same way.

Handle PDFs and documents

If the application generates, displays, or links to PDFs, test them with a screen reader.

A PDF created from a scanned image has no text layer. A screen reader reads nothing. The fix is either to add a text layer (OCR) or to provide an accessible HTML alternative alongside the PDF.

Even PDFs with a text layer can have accessibility problems. Missing heading structure, missing alt text on embedded images, tables with no header associations, and incorrect reading order. Adobe Acrobat Pro has a built-in accessibility checker. The free PAC (PDF Accessibility Checker) from the Access For All Foundation is another option.

This applies to Word documents, PowerPoint files, and any other content the team publishes. If users with disabilities need to access it, it needs to be tested.

Check third-party components

Embedded third-party code is a common source of accessibility failures.

Chat widgets that trap keyboard focus. Cookie consent banners that cover the focus indicator on the page beneath them. These issues do not show up in code reviews because the code is not yours.

Deque's vendor management guidance makes a straightforward point: embedding third-party software means inheriting its accessibility failures. Users do not know or care which part of the page came from a vendor.

Before integrating a third-party component, test it with a keyboard and a screen reader. If the vendor cannot provide a VPAT (Voluntary Product Accessibility Template) or show results of their own accessibility testing, that is a red flag. Build accessibility requirements into procurement contracts. Require vendors to fix accessibility issues within a defined timeframe after they are reported.

For components already in production, include them in regular accessibility scans. Axe-core flags violations in vendor code the same way it flags first-party code. File the results with the vendor and track them.

Test video and audio content

Any product that includes onboarding walkthroughs, help videos, or embedded media content needs caption and transcript testing.

WCAG 1.2.2 requires captions for prerecorded video with audio. WCAG 1.2.5 requires audio descriptions for prerecorded video where visual information is not conveyed in the existing audio track. Transcripts are required for audio-only content.

The test: play every video in the product with the sound off. If the content cannot be followed from captions alone, a deaf user cannot follow it either. Check that captions are synchronized and accurate, with speakers identified. Auto-generated captions from YouTube or similar services get technical terms and proper names wrong regularly. Someone needs to review them.

Build captioning into the production workflow. Retrofitting captions after the fact is slower and more expensive than adding them during editing.

Make results visible to the whole team

Accessibility findings that live in a QA tool nobody checks do not get fixed.

Share HTML reports from tools like wick-a11y or axe with designers. These reports include annotated screenshots showing which elements failed and why. A designer can look at the report and know what to change without a meeting.

File violations as tickets with screenshots. Each violation becomes a trackable item with an owner and a status. Include the WCAG success criterion and the affected page in the ticket.

Bring accessibility findings into sprint reviews. Show the team a screen reader navigating a page that has problems. Show them the same page after the fix. That kind of demo sticks longer than a ticket.

Resources

For tool-specific implementation guides, see the companion articles:

Find me on LinkedIn.

Accessible web testing with Playwright and Axe Core

Vitaly Skadorva — Wed, 08 Apr 2026 02:13:31 +0000

This is the third article in a series on accessibility testing for QA engineers. The first one covered Cypress with axe-core and went into why accessibility testing matters, what the 2025 WebAIM Million report found, and the legal landscape around ADA and the European Accessibility Act. The second explored wick-a11y as an alternative Cypress plugin with built-in HTML reporting.

This article adapts every example to Playwright using @axe-core/playwright, Deque's official integration. The accessibility concepts are identical. The code is different.

Introducing the tools

Playwright is a cross-browser testing framework from Microsoft. It runs tests against Chromium, Firefox, and WebKit, handles auto-waiting natively, and has had keyboard methods (page.keyboard.press()) since its first release. No plugin needed for that. Playwright added locator.ariaSnapshot() in v1.49, which captures the accessibility tree as structured YAML. Version 1.59 promoted it to a page-level method (page.ariaSnapshot()) and added depth and mode options for controlling how much of the tree you get back. I'll show how that pairs with axe scans later in this article.

Axe-core (currently at v4.11.1) is an accessibility testing engine built by Deque Systems. It evaluates DOM elements against WCAG rules and returns a structured list of violations with severity levels and references to specific guidelines. A recent release corrected the luminance threshold used in color contrast checks, so if you upgrade from an older version, expect some borderline contrast results to shift.

The @axe-core/playwright package (also v4.11.1, versioned in lockstep with axe-core) connects the two. It provides an AxeBuilder class with a chainable API for scoping, filtering, and running scans. Unlike cypress-axe, there's no injectAxe() step. The package handles injection automatically.

Installation and setup

One package:

npm install --save-dev @axe-core/playwright

No support file to edit, no import to register globally. You import AxeBuilder in each test file where you need it:

import AxeBuilder from '@axe-core/playwright';

Your first test:

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('home page has no detectable violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

The terminal is filled with a structured violations array. Playwright's default reporter made it easier to read.

Basic usage patterns

Before jumping into full examples, here are a few patterns that have held up over time.

Scope your checks

You don't need to scan the entire page after every interaction. The include and exclude methods scope the check to specific elements:

const results = await new AxeBuilder({ page })
  .include('[role="dialog"]')
  .analyze();

const results = await new AxeBuilder({ page })
  .include('form')
  .exclude('.third-party-widget')
  .analyze();

Filter by WCAG tags

If you need to check against a specific standard, use withTags:

const results = await new AxeBuilder({ page })
  .withTags(['wcag2a', 'wcag2aa'])
  .analyze();

Filter by severity after analysis

@axe-core/playwright doesn't have a built-in severity filter like cypress-axe's includedImpacts. You filter the results array instead:

const results = await new AxeBuilder({ page }).analyze();
const critical = results.violations.filter(
  (v) => v.impact === 'critical'
);
expect(critical).toEqual([]);

This approach is actually more flexible. You can fail the test on critical violations while logging serious ones to the console in the same run:

const results = await new AxeBuilder({ page }).analyze();
const critical = results.violations.filter(
  (v) => v.impact === 'critical'
);
const serious = results.violations.filter(
  (v) => v.impact === 'serious'
);

if (serious.length > 0) {
  console.log('Serious violations (not failing):', serious);
}

expect(critical).toEqual([]);

Wait for single-page apps to finish rendering

await page.waitForSelector('.loading-spinner', { state: 'hidden' });
await page.waitForSelector('[data-loaded="true"]');
const results = await new AxeBuilder({ page }).analyze();

Readable violation output

Playwright's default test reporter already formats assertion failures better than most tools. But when you want a clean summary in CI logs, a small helper does the job:

import { AxeResults } from 'axe-core';

function logViolations(results: AxeResults) {
  const violations = results.violations;
  if (violations.length === 0) return;

  console.log(
    `${violations.length} accessibility violation${
      violations.length === 1 ? '' : 's'
    } detected`
  );

  console.table(
    violations.map(({ id, impact, description, nodes }) => ({
      id,
      impact,
      description,
      nodes: nodes.length,
    }))
  );
}

Usage:

const results = await new AxeBuilder({ page }).analyze();
logViolations(results);
expect(results.violations).toEqual([]);

Example 1: E2E test with real API calls

This example uses a weather app that calls a live API. The test types a city name, waits for search results, selects a city, verifies the weather display updates, and then runs an accessibility check on the final state.

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test.describe('E2E: city search + accessibility', () => {
  test('checks accessibility after a search', async ({ page }) => {
    await page.goto('/');

    // set up the listener before the action that triggers the request
    const searchResponsePromise = page.waitForResponse(
      (resp) => resp.url().includes('/search?q=') && resp.status() === 200
    );
    await page.locator('#city-input').fill('Toronto');
    await searchResponsePromise;

    // same pattern: listener first, then the action
    const weatherResponsePromise = page.waitForResponse(
      (resp) => resp.url().includes('/weather?') && resp.status() === 200
    );
    await page.locator('#city-select').selectOption({ index: 1 });
    const weatherResponse = await weatherResponsePromise;
    const weatherData = await weatherResponse.json();

    // verify weather display
    await expect(
      page.locator('[data-cy="weather-display"]')
    ).toContainText(weatherData.name);

    // accessibility check after dynamic content loads
    const results = await new AxeBuilder({ page }).analyze();
    expect(results.violations).toEqual([]);
  });
});

One thing I learned running this: Playwright's waitForResponse gives you precise control over when the page is ready for an accessibility scan. No guessing with arbitrary timeouts. The key detail is setting up the response promise before the action that triggers the request. If you await page.waitForResponse(...) after fill(), a fast API can respond before the listener is active, and the test fails.

Example 2: Scoped checks for modals and dynamic content

Modals and form error states are where I've seen the most accessibility regressions ship. The content appears dynamically, and ARIA attributes on dialogs are the kind of thing that works fine until someone changes the markup.

Scoping the check to the modal DOM avoids noise from the rest of the page:

test('checks modal accessibility', async ({ page }) => {
  await page.goto('/');

  await page.getByRole('button', { name: 'Open Modal' }).click();
  await expect(page.locator('[data-cy="modal-overlay"]')).toBeVisible();

  // scan only the modal
  const results = await new AxeBuilder({ page })
    .include('[data-cy="modal-overlay"]')
    .analyze();

  expect(results.violations).toEqual([]);
});

That .include() call tells axe to evaluate only the modal, not the entire page behind it.

For forms, the same idea applies: check accessibility both before and after triggering validation errors. Error messages need aria-live regions to be announced by screen readers, and invalid fields need aria-invalid plus aria-describedby linking them to the error text.

Example 3: Keyboard navigation

Playwright has had page.keyboard.press() since its first release. No plugin required. This is useful for testing focus management, which is one of the most common accessibility failures and one that axe-core can't catch on its own.

test('modal traps focus and closes on Escape', async ({ page }) => {
  await page.goto('/');

  await page.getByRole('button', { name: 'Open Modal' }).click();
  await expect(page.locator('[data-cy="modal-overlay"]')).toBeVisible();

  // focus should start on the first focusable element
  await expect(page.locator('[data-cy="modal-close-btn"]')).toBeFocused();

  // Tab should stay inside the modal
  await page.keyboard.press('Tab');
  await expect(
    page.locator('[data-cy="modal-overlay"]').locator(':focus')
  ).toBeVisible();

  // Escape should close the modal
  await page.keyboard.press('Escape');
  await expect(page.locator('[data-cy="modal-overlay"]')).toHaveCount(0);

  // focus should return to the trigger button
  await expect(
    page.getByRole('button', { name: 'Open Modal' })
  ).toBeFocused();

  // run axe after the modal closes
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

This test checks four things that axe-core can't: that focus moves into the modal on open, that Tab doesn't escape the modal boundary, that Escape closes the dialog, and that focus returns to the button that triggered it. Those four behaviors are all WCAG 2.4.3 (Focus Order) requirements.

Example 4: Storybook integration

If your team maintains a component library, Storybook is a natural place to catch accessibility issues before they spread into applications. The test visits the Storybook iframe URL for each component story:

test.describe('Storybook: CitySelector', () => {
  test('has no accessibility violations', async ({ page }) => {
    await page.goto(
      '/iframe.html?id=components-cityselector--default'
    );

    // wait for the component to render
    await page.locator('[data-cy="city-selector"]').waitFor();

    const results = await new AxeBuilder({ page })
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();

    expect(results.violations).toEqual([]);
  });
});

Each story gets its own scan. Missing labels and incorrect ARIA roles show up at the component level, long before anyone integrates the component into a page.

Example 5: Component tests

Playwright has experimental component testing for React and Vue. It mounts the component directly in a real browser. The feedback loop is fast.

import { test, expect } from '@playwright/experimental-ct-react';
import AxeBuilder from '@axe-core/playwright';
import CitySelector from './CitySelector';

test('<CitySelector /> has no critical violations', async ({ mount, page }) => {
  await mount(<CitySelector />);

  const results = await new AxeBuilder({ page }).analyze();
  const critical = results.violations.filter(
    (v) => v.impact === 'critical' || v.impact === 'serious'
  );

  expect(critical).toEqual([]);
  await expect(page.locator('[data-cy="city-selector"]')).toBeVisible();
});

This is the closest you can get to catching problems while you're still building the component. If the label is missing here, it will be missing everywhere it's used.

Note: Playwright 1.59 removed the @playwright/experimental-ct-svelte package. React and Vue component testing are still supported.

CI/CD integration

Playwright has a built-in GitHub Actions setup. Here's a minimal workflow:

name: Playwright Accessibility Tests
on:
  pull_request:
    branches: [develop, intg]

jobs:
  playwright-run:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test --fail-on-flaky-tests
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

If a run fails, the uploaded HTML report includes screenshots, traces, and the full list of violations. Playwright's built-in reporter is detailed enough.

The --fail-on-flaky-tests flag changes how retries are handled. By default, the test runner exits with code 0 when a failed test passes on retry. With this flag, it exits with code 1 instead. Accessibility tests that flake because a spinner wasn't gone when axe ran are exactly the kind of false pass you want to catch in CI.

The same release added a 'retain-on-failure-and-retries' trace mode. It records a trace for every attempt and keeps them all when a test fails.

Playwright 1.59 also added npx playwright trace, which lets you explore traces from the command line without opening the trace viewer. After a CI failure, you can run npx playwright trace actions --grep="expect" to jump straight to the failing assertion. I've found this faster than downloading the HTML report when I already know the test name and just need to see what axe returned.

Start with a narrow gate. Filter for critical violations only and widen it over time as the backlog shrinks.

Inspecting the accessibility tree

Axe-core tells you what's broken. It doesn't show you what the tree looks like. Playwright added locator.ariaSnapshot() in v1.49 for capturing the accessibility tree of a specific element. Version 1.59 added the page-level page.ariaSnapshot() shorthand (equivalent to page.locator('body').ariaSnapshot()) and new depth and mode options so you can control how deep the snapshot goes. The output is structured YAML:

const snapshot = await page.ariaSnapshot();
console.log(snapshot);

The output reads like what a screen reader sees: headings with levels, buttons with names, links with text, form fields with labels. If a button has no accessible name, it shows up as an empty string. If a heading hierarchy jumps from h2 to h5, you see it.

I started using this alongside axe scans. Axe catches the WCAG violations. The snapshot shows structural problems that axe doesn't flag: a reading order that makes no sense, or a landmark region with the wrong content. You can scope it to a specific element, too:

const modalSnapshot = await page.locator('[role="dialog"]').ariaSnapshot();
console.log(modalSnapshot);

For regression testing, toMatchAriaSnapshot() lets you lock down the tree structure:

await expect(page.locator('nav')).toMatchAriaSnapshot(`
  - navigation:
    - link "Home"
    - link "Products"
    - link "Contact"
`);

If someone removes a nav link or changes a heading level, the test fails with a diff.

Playwright MCP and the accessibility tree

Microsoft released @playwright/mcp in early 2025, and it has been getting updates with every Playwright release since. It's a Model Context Protocol server that gives AI agents browser control through structured accessibility snapshots. Instead of processing screenshots, the agent reads the same tree that screen readers use: element names, roles, and states.

The connection to this article is practical. If you're already running axe scans, you can point an AI agent at your app through this MCP server, and the agent navigates using the accessibility tree. If your app's tree is broken (missing names or incorrect roles), the AI agent struggles in the same way a screen reader user does. Accessibility testing and AI-driven testing share the same foundation: a well-structured accessibility tree.

Playwright 1.59 added browser.bind(), which lets you attach @playwright/mcp or playwright-cli to a browser your tests already started. You run your accessibility suite, and an AI agent can inspect the same session. Set PLAYWRIGHT_DASHBOARD=1 to open a live dashboard of all browser sessions.

npx @playwright/mcp@latest

npm install -g @playwright/cli@latest

These tools are separate from @axe-core/playwright and serve a different purpose. Axe finds WCAG violations. Playwright MCP and CLI let agents interact with your app through its accessibility tree. Together, they cover automated rule checking and structural navigation.

Recording accessibility walkthroughs

Playwright 1.59 also shipped a Screencast API (page.screencast) that records video with precise start/stop control. What makes it relevant here is the showActions() method: it annotates the recording with visual highlights on every element the test interacts with.

await page.screencast.start({ path: 'a11y-keyboard-walkthrough.webm' });
await page.screencast.showActions({ position: 'top-right' });

// ... run the keyboard navigation test ...

await page.screencast.stop();

You can also add chapter titles with showChapter() to break the video into labeled sections.

The part automation can't do

Automated scanners catch roughly 30 to 50 percent of accessibility issues. They find missing alt text and broken ARIA references. They can't tell you whether alt text is meaningful or whether a screen reader user would understand your page's reading order.

Dynamic content in single-page apps can also cause false negatives. If the page hasn't finished rendering when axe runs, it'll miss real problems or flag temporary states. Wait for your app's "ready" signal:

await page.waitForSelector('.loading-spinner', { state: 'hidden' });
await page.waitForSelector('[data-loaded="true"]');
const results = await new AxeBuilder({ page }).analyze();

Manual checks remain necessary. Tab through the page and run a screen reader (NVDA on Windows, VoiceOver on macOS) before each release. Ten minutes of that catches things no scanner will find.

Resources

Find me on LinkedIn.

Accessible web testing with Cypress and wick-a11y

Vitaly Skadorva — Wed, 01 Apr 2026 02:01:09 +0000

I spent a couple of hours building a custom logging callback for cypress-axe. It formatted violations into a console table and registered Cypress tasks in the config file. It worked. Then I installed wick-a11y and got better output with zero custom code.

This is the second article in my accessibility testing series. The first one covered Cypress with cypress-axe, and you can find it here:

Vitaly Skadorva for Cypress

Mar 23

Accessible web testing with Cypress and Axe Core

#cypress #a11y #testing #webdev

Comments

9 min read

Sebastian Clavijo Suero (@sebastianclavijo) built wick-a11y on top of the same axe-core engine that powers cypress-axe. The difference is what happens after the scan. Where cypress-axe gives you a raw violations array and leaves the rest to you, wick-a11y processes the results into color-coded Cypress logs with visual highlighting in the runner, plus HTML reports with annotated screenshots and fix guidance. All of it works out of the box.

What wick-a11y adds over cypress-axe

I've been using cypress-axe in my project for some time, and it works well. However, there is a gap between when "axe-core detects violations" and when "the team understands what needs to be fixed." To address this, I created a terminalLog callback and implemented custom severity filtering. I've noticed that many teams do something similar to this.

The API itself shows the gap. cypress-axe uses positional arguments: cy.checkA11y(context, options, violationCallback, skipFailures). When you only need the skip flag, you end up writing cy.checkA11y(null, null, terminalLog, true). Three nulls to reach the one parameter you care about. wick-a11y uses cy.checkAccessibility(context, options) with a clean options object. Everything goes in one place.

wick-a11y closes that gap with features that come built in. It uses cy.checkAccessibility() instead of cy.checkA11y(), and here's what you get without writing any custom code:

Violations appear in the Cypress log grouped by severity, with a count summary (critical, serious, moderate, minor). Hovering over a violation in the log highlights the affected DOM element on the page with a color-coded outline. Clicking it prints full details to the browser console, including the WCAG rule and fix guidance.

HTML reports are generated automatically for every test that finds violations. Each report includes violation details grouped by severity and a screenshot highlighting the affected elements. The reports themselves are mostly WCAG 2.2 AAA compliant and support full keyboard navigation. An accessibility testing tool whose own reports are accessible is a detail Sebastian clearly thought about.

There's also a voice feature. When enabled, wick-a11y reads violation summaries aloud at the suite, test, violation type, and individual element levels. Sebastian added this because many people testing accessibility have disabilities themselves. The Cypress runner is not particularly accessible, and this gives auditory feedback for people who need it.

The official Cypress blog featured wick-a11y in their Open Source Accessibility Plugins in Cypress post, describing it as adding visual, reporting, and voice dimensions to the cypress-axe plugin.

Installation and setup

Two packages (wick-a11y pulls in cypress-axe as a dependency):

npm install --save-dev wick-a11y axe-core

Add the accessibility tasks to your cypress.config.js:

const addAccessibilityTasks = require('wick-a11y/accessibility-tasks');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      addAccessibilityTasks(on);
    },
  },
});

Import the custom commands in cypress/support/e2e.js:

import 'wick-a11y';

That's it. No terminalLog callback, no task registration for log and table, and no custom severity filtering code. The plugin manages everything.

HTML reports are saved to cypress/accessibility by default. You can change this:

module.exports = defineConfig({
  accessibilityFolder: 'cypress/your-reports-folder',
});

Basic usage patterns

Full page scan

it('home page has no detectable violations', () => {
  cy.visit('/');
  cy.injectAxe();
  cy.checkAccessibility();
});

When I first ran this on my weather app, the Cypress log showed a severity summary at the top: 3 critical, 1 serious, 2 moderate, 1 minor. Each violation is listed below, along with the affected elements. On the page itself, every element with a violation had a colored outline matching its severity. Red for critical, blue for minor, and the rest in between.

Scope to an element

cy.checkAccessibility('[role="dialog"]');
cy.checkAccessibility('form');

Filter by severity

cy.checkAccessibility(null, {
  includedImpacts: ['critical', 'serious'],
});

Warn without failing

This is the feature I was building manually with the skipFailures flag in cypress-axe. The difference: cypress-axe's skipFailures is a boolean. Either all violations fail the test, or none do. wick-a11y has onlyWarnImpacts, which lets you pick which severity levels to warn without failing:

cy.checkAccessibility(null, {
  onlyWarnImpacts: ['moderate', 'minor'],
});

This keeps the pipeline green while still surfacing moderate and minor issues in the Cypress log and HTML report. The test fails only for critical and serious violations. With cypress-axe, you'd have to build that filtering yourself.

Filter by WCAG tags

wick-a11y supports WCAG 2.2 at all three levels (A, AA, AAA):

cy.checkAccessibility(null, {
  runOnly: {
    type: 'tag',
    values: ['wcag2a', 'wcag2aa'],
  },
});

Custom severity styles

You can override the default highlight colors for each severity level:

cy.checkAccessibility(null, {
  impactStyling: {
    critical: { icon: '🔴', style: 'fill: #E24B4A; stroke: #E24B4A;' },
    serious: { icon: '🟠', style: 'fill: #EF9F27; stroke: #EF9F27;' },
  },
});

Control HTML report generation

// detailed report (default)
cy.checkAccessibility(null, { generateReport: 'detailed' });

// basic report (smaller file, no JavaScript)
cy.checkAccessibility(null, { generateReport: 'basic' });

// no report
cy.checkAccessibility(null, { generateReport: 'none' });

Example 1: E2E test with real API calls

describe('E2E: city search + accessibility', () => {
  beforeEach(() => {
    cy.visit('/');
    cy.injectAxe();
  });

  it('checks accessibility after a search', () => {
    cy.intercept('/search?q=*').as('search');
    cy.intercept('/weather?*').as('weather');

    cy.get('[data-cy="city-selector"]').type('Toronto');
    cy.wait('@search').then((interception) => {
      expect(interception.response.statusCode).to.eq(200);
    });

    cy.get('#city-select').select(1);
    cy.wait('@weather').then((interception) => {
      const cityName = interception.response.body.name;
      cy.get('[data-cy="weather-display"]')
        .should('be.visible')
        .and('contain', cityName);
    });

    cy.checkAccessibility(null, {
      onlyWarnImpacts: ['moderate', 'minor'],
    });
  });
});

After the test runs, wick-a11y generates an HTML report in cypress/accessibility that groups violations by severity. The screenshot at the bottom of the report shows my weather app with the select dropdown highlighted in red (critical: no accessible name) and several text elements outlined in orange (serious: contrast ratio). I sent that report to the team, and they fixed the dropdown label within the hour. With cypress-axe, I would have had to explain the console output. The report explained itself.

Example 2: Scoped checks for modals and dynamic content

describe('Weather app modal', () => {
  beforeEach(() => {
    cy.visit('http://localhost:8080/');
    cy.injectAxe();
  });

  it('checks modal accessibility', () => {
    cy.contains('button', 'Open Modal').click();
    cy.checkAccessibility('[data-cy="modal-overlay"]', {
      onlyWarnImpacts: ['moderate', 'minor'],
    });
    cy.get('[data-cy="modal-overlay"]').should('be.visible');
  });
});

Hovering over a violation in the Cypress log highlights the affected element in the runner. I found a close button with no accessible name this way. In the runner, the button lit up red when I hovered over the label violation in the log. That visual connection between the log entry and the actual element on the page is something I never had with cypress-axe.

Example 3: Keyboard navigation with cy.press()

wick-a11y handles the axe-core scan. For keyboard behavior, you still need cy.press() (Cypress 14+):

describe('Modal keyboard navigation', () => {
  beforeEach(() => {
    cy.visit('/');
    cy.injectAxe();
  });

  it('traps focus inside the modal and closes on Escape', () => {
    cy.contains('button', 'Open Modal').click();
    cy.get('[data-cy="modal-overlay"]').should('be.visible');

    cy.focused().should('have.attr', 'data-cy', 'modal-close-btn');

    cy.press('Tab');
    cy.focused().should('be.within', cy.get('[data-cy="modal-overlay"]'));

    cy.press('Escape');
    cy.get('[data-cy="modal-overlay"]').should('not.exist');

    cy.focused().should('contain', 'Open Modal');

    cy.checkAccessibility(null, {
      onlyWarnImpacts: ['moderate', 'minor'],
    });
  });
});

This test evaluates four aspects that axe-core cannot check: 1) whether focus moves into the modal when it opens, 2) whether the Tab key does not allow focus to escape the modal boundary, 3) whether the Escape key closes the dialog, and 4) whether focus returns to the button that triggered the modal. All of these elements are requirements of WCAG 2.4.3 (Focus Order).

Example 4: Storybook integration

describe('Storybook: CitySelector', () => {
  beforeEach(() => {
    cy.visit(
      'http://localhost:6006/iframe.html?id=components-cityselector--default'
    );
    cy.injectAxe();
  });

  it('has no accessibility violations', () => {
    cy.checkAccessibility(null, {
      runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa'],
      },
    });
  });
});

Each story gets its own HTML report. I started running these for our shared component library after a dropdown component shipped to multiple applications without an accessible name. The wick-a11y reports made it easy to share findings with the team because the screenshots showed exactly which elements failed and why.

Example 5: Component tests

import CitySelector from './CitySelector';

describe('<CitySelector />', () => {
  beforeEach(() => {
    cy.injectAxe();
  });

  it('renders with no critical violations', () => {
    cy.mount(<CitySelector />);
    cy.checkAccessibility(null, {
      includedImpacts: ['serious', 'critical'],
    });
    cy.get('[data-cy="city-selector"]').should('be.visible');
  });
});

If the label is missing here, it will be missing everywhere the component is used. wick-a11y's HTML report for component tests includes the same annotated screenshot and fix guidance as the E2E reports, so the developer working on the component can see the problem and the suggested fix in a single document.

cypress-axe vs wick-a11y: when to use which

Both use the same axe-core engine underneath. The scan results are the same, but the differences lie elsewhere.

cypress-axe gives you the raw results and leaves the presentation to you. You write the logging callbacks, register the tasks, and build your own reporting. If you want minimal dependencies and full control, it works. But you'll write and maintain custom code that wick-a11y provides out of the box.

wick-a11y gives you color-coded Cypress logs, visual highlighting in the runner, HTML reports with annotated screenshots, and voice feedback. If your team needs to share findings with designers or product managers who don't read terminal output, the built-in reports save real time.

A note on cypress-axe maintenance

One thing worth knowing: cypress-axe caps some features that axe-core supports natively. Axe-core returns "incomplete" results for checks it can't fully confirm, such as certain color-contrast situations that require manual review. cypress-axe filters those out before they reach your test. Sebastian raised this as issue #191 in October 2025. As of this writing, it's still open with no response.

The maintenance gap goes beyond that one issue. The cypress-axe new API RFC (issue #75) has been open since November 2020 with community demand but no implementation. Most recent activity has been version bumps to keep pace with new Cypress releases. By contrast, wick-a11y has had over 14 releases in just over a year. Version 2.2.0 shipped for Cypress 15 within ten days of the Cypress release. Version 3.0.1 is the latest as of March 2026. Sebastian tracks Cypress major versions and publishes compatibility updates fast.

Sebastian's plan is to remove the cypress-axe dependency from wick-a11y and use axe-core directly. Since cypress-axe is a thin wrapper over axe-core with one additional filtering feature that wick-a11y already bypasses for its warnings system, the change should be transparent to users.

Resources

The code examples in this article use a weather app I built for testing. My book Ultimate Web Automation Testing with Cypress covers the Cypress framework end to end.

Find me on LinkedIn.

Accessible web testing with Cypress and Axe Core

Vitaly Skadorva — Mon, 23 Mar 2026 14:35:05 +0000

Why accessibility matters

About 15% of people worldwide live with some form of disability. When a checkout flow can't be completed with a keyboard, or a form has no labels for a screen reader, those users leave. Quietly.

The legal aspect has caught up. The ADA has been enforcing equal access to digital services in the US for years. In Europe, the European Accessibility Act went into effect on June 28, 2025.

Websites serving EU users now need to comply with WCAG 2.2 Level AA, and enforcement has already begun. In France, disability organizations filed court proceedings against major retailers within months of the deadline. Germany set fines up to €100,000 per violation.

Accessible design also improves the experience for people who don't identify as having a disability. Sufficient contrast helps someone using a laptop when the sun is hitting the screen. Keyboard navigation helps someone with a broken trackpad.

What WebAIM found in 2025

The 2025 WebAIM Million report found that 94.8% of the top million home pages have detectable WCAG failures. That's down slightly from 95.9% the year before. The average page has 51 errors.

One number from the report surprised me: pages using ARIA averaged 57 errors, while pages without it averaged 27. Incorrect ARIA implementations cause more problems than they solve.

50% of individuals with disabilities say they've seen no improvement in web accessibility over time. I kept coming back to that one while putting this article together.

Introducing the tools

Cypress is a JavaScript-based end-to-end testing framework for modern web apps. It runs directly in the browser and handles waits automatically. Cypress has a command cy.press(), which dispatches native keyboard events like Tab and Escape directly to the browser. That matters for accessibility testing because keyboard navigation is one of the first things WCAG checks require.

Axe-core is an accessibility testing engine built by Deque Systems. It evaluates DOM elements against WCAG rules and returns a structured list of violations with severity levels and references to specific guidelines.

The cypress-axe plugin connects the two. It lets you call cy.checkA11y() inside any Cypress test to run an axe-core scan at that exact moment in the DOM lifecycle, after a page load or after a modal opens. The checks live right next to the interactions that create the DOM state you want to test. The plugin's API hasn't changed in over a year, so the examples below should work on any recent version.

Installation and setup

Three packages, one import:

npm install --save-dev cypress axe-core cypress-axe

Import the plugin into your Cypress support file:

// cypress/support/e2e.js
import 'cypress-axe';

After loading any page, inject axe-core:

cy.visit('/');
cy.injectAxe();

Your first test can be a few lines:

it('home page has no detectable violations', () => {
  cy.visit('/');
  cy.injectAxe();
  cy.checkA11y();
});

Basic usage patterns

Before jumping into full examples, here are a few patterns that have held up over time.

Scope your checks

You don't need to scan the entire page after every interaction. For modals and forms, scoping the check to the relevant element reduces noise and runs faster:

cy.checkA11y('[role="dialog"]');
cy.checkA11y('form');

Filter by severity

A common adoption strategy: fail the build only on critical violations at first. Once you fix the critical violations, you can move to the serious ones.

cy.checkA11y(null, { includedImpacts: ['critical'] });

Scope to specific WCAG tags

If you need to check against a specific standard, you can pass runOnly with WCAG tags:

cy.checkA11y('.example-class', {
  runOnly: {
    type: 'tag',
    values: ['wcag2a'],
  },
});

Log without failing

During initial adoption, when you want visibility but aren't ready to block the pipeline, the fourth argument tells cypress-axe to log violations without failing the test:

cy.checkA11y(null, null, null, true);

Retry for async content

Single-page apps sometimes aren't fully rendered when the check runs. You can configure retries:

cy.checkA11y(null, {
  retries: 3,
  interval: 100,
});

Custom logging that makes violations readable

The default failure output from cypress-axe is not helpful in a terminal. A small callback function changes that completely.

Here's the one I've been using. It goes at the top of your spec file or in a shared utility:

function terminalLog(violations) {
  cy.task(
    'log',
    `${violations.length} accessibility violation${
      violations.length === 1 ? '' : 's'
    } ${violations.length === 1 ? 'was' : 'were'} detected`
  );

  const violationData = violations.map(
    ({ id, impact, description, nodes }) => ({
      id,
      impact,
      description,
      nodes: nodes.length,
    })
  );

  cy.task('table', violationData);
}

You need to register the task handlers in cypress.config.js, inside your setupNodeEvents function:

module.exports = {
  e2e: {
    setupNodeEvents(on, config) {
      on('task', {
        log(message) {
          console.log(message);
          return null;
        },
        table(message) {
          console.table(message);
          return null;
        },
      });
    },
  },
};

Then pass the callback as the third argument:

cy.checkA11y(null, null, terminalLog);

Instead of a long, confusing list of text, you get a clear console table that shows each violation ID, its severity, a short description, and the number of nodes affected. The first time I ran it, the output showed color-contrast as serious (75 nodes) and select-name as critical (1 node). The select dropdown got fixed that same week.

Example 1: E2E test with real API calls

describe('E2E: city search + accessibility', () => {
  beforeEach(() => {
    cy.visit('/');
    cy.injectAxe();
  });

  it('checks accessibility after a search', () => {
    cy.intercept('/search?q=*').as('search');
    cy.intercept('/weather?*').as('weather');

    cy.get('[data-cy="city-selector"]').type('Toronto');
    cy.wait('@search').then((interception) => {
      expect(interception.response.statusCode).to.eq(200);
    });

    cy.get('#city-select').select(1);
    cy.wait('@weather').then((interception) => {
      expect(interception.response.statusCode).to.eq(200);
      const cityName = interception.response.body.name;
      cy.get('[data-cy="weather-display"]')
        .should('be.visible')
        .and('contain', cityName);
    });

    cy.checkA11y(null, null, terminalLog, true);
  });
});

Example 2: Scoped checks for modals and dynamic content

Modals and form error states are where I've seen the most accessibility regressions. The content appears dynamically, and ARIA attributes on dialogs are the kind of thing that works fine until someone changes the markup.

Scoping the check to the modal DOM avoids noise from the rest of the page:

describe('Weather app modal', () => {
  beforeEach(() => {
    cy.visit('http://localhost:8080/');
    cy.injectAxe();
  });

  it('checks modal accessibility', () => {
    cy.contains('button', 'Open Modal').click();
    cy.get('[data-cy="modal-overlay"]').should('be.visible');
    cy.checkA11y('[data-cy="modal-overlay"]', null, terminalLog, true);
  });
});

That scoped selector tells axe to evaluate only the modal, not the entire page behind it. It catches missing aria-modal and contrast problems inside the dialog.

For forms, the same idea applies: check accessibility both before and after triggering validation errors.

Example 3: Keyboard navigation with cy.press()

Cypress added the cy.press() command, which sends native keyboard events to the browser. This is useful for testing focus management, which is one of the most common accessibility failures and one that cy.checkA11y() can't catch on its own.

describe('Modal keyboard navigation', () => {
  beforeEach(() => {
    cy.visit('/');
    cy.injectAxe();
  });

  it('focuses inside the modal and closes on Escape', () => {
    cy.contains('button', 'Open Modal').click();
    cy.get('[data-cy="modal-overlay"]').should('be.visible');

    // focus should start on the first focusable element inside the modal
    cy.focused().should('have.attr', 'data-cy', 'modal-close-btn');

    // Tab through the modal, focus should stay inside
    cy.press('Tab');
    cy.focused().should('be.within', cy.get('[data-cy="modal-overlay"]'));

    // Escape should close the modal
    cy.press('Escape');
    cy.get('[data-cy="modal-overlay"]').should('not.exist');

    // focus should return to the trigger button
    cy.focused().should('contain', 'Open Modal');

    // run axe after the modal closes
    cy.checkA11y(null, null, terminalLog, true);
  });
});

Example 4: Storybook integration

If your team maintains a component library, Storybook is a natural place to catch accessibility problems before they spread into applications. The test visits the Storybook iframe URL for each component story:

describe('Storybook: CitySelector', () => {
  beforeEach(() => {
    cy.visit(
      'http://localhost:6006/iframe.html?id=components-cityselector--default'
    );
    cy.injectAxe();
  });

  it('has no accessibility violations', () => {
    cy.checkA11y(null, null, terminalLog, true);
  });
});

Each story gets its own scan. Missing labels and incorrect ARIA roles show up at the component level.

Example 5: Component tests

Cypress component testing mounts a React, Vue, Angular, or Svelte component directly in the test runner. No dev server, no full application. The feedback loop is under a second.

import CitySelector from './CitySelector';

describe('<CitySelector />', () => {
  beforeEach(() => {
    cy.injectAxe();
  });

  it('renders with no critical violations', () => {
    cy.mount(<CitySelector />);
    cy.checkA11y(
      null,
      { includedImpacts: ['serious', 'critical'] },
      terminalLog,
      true
    );
    cy.get('[data-cy="city-selector"]').should('be.visible');
  });
});

This is the closest you can get to catching problems while you're still building the component. If the label is missing here, it will be missing everywhere it's used. You can combine this with visual regression and snapshot tests for a broader check without adding another tool.

The part automation can't do

Automated scanners catch approximately 30 to 50 percent of accessibility issues. They find missing alt text and broken ARIA references. They can't tell you whether alt text is meaningful or whether a screen reader user would understand your page's reading order.

Dynamic content in single-page apps can also cause false negatives. If the page hasn't finished rendering when axe runs, it'll miss real problems or flag temporary states. Wait for your app's "ready" signal:

cy.get('.loading-spinner').should('not.exist');
cy.get('[data-loaded="true"]').should('exist');
cy.checkA11y();

Manual checks remain necessary. Tab through the page and run a screen reader (NVDA on Windows, VoiceOver on macOS) before each release. Ten minutes of that catches things no scanner will find.

If you're already on Cypress Cloud

Everything in this article uses the free, open-source cypress-axe plugin. But if your team already records test runs to Cypress Cloud with Test Replay, there's a paid add-on called Cypress Accessibility that takes a different approach.

There is no setup. No cy.injectAxe(), no cy.checkA11y(), no callback functions. It runs axe-core server-side against every DOM state your tests already capture. The accessibility checks happen after the test finishes, so they don't slow down your test suite or introduce flakiness.

What you get is a dashboard in Cypress Cloud that groups violations by page and component. Each violation links to a full DOM snapshot where you can inspect the element in context. You can compare two runs side by side to see only the new issues introduced by a specific commit. And there's a Results API you can call from your CI pipeline to fail a build based on your own severity thresholds.

The feature I found most useful was the run comparison. When reviewing a pull request, I could see whether the PR introduced new violations or if they were pre-existing. That made code review conversations about accessibility much shorter.

It also has Jira integration for filing violations directly as tickets, and configurable profiles so you can apply different rules to different branches or teams.

The free cypress-axe approach from this article gives you full control and works anywhere Cypress runs. Cypress Accessibility is worth looking at if your team needs a more out-of-the-box solution that doesn't require modifying existing tests, covers all states and pages automatically, and adds some extra checks and analytics on top.

One thing Cypress Accessibility does that axe-core cannot: it watches how your tests actually interact with elements on the page. Cypress added a custom rule called "Interactive elements should be semantically correct" that flags elements your tests click or type into when those elements use the wrong semantic markup. A div with an onClick handler that behaves like a button, or an image used as a tooltip trigger. These pass every axe-core scan because axe-core evaluates the DOM as it is. Cypress Accessibility evaluates how the DOM is being used, which is how it catches problems that static scans miss entirely.

For a deeper comparison of the two approaches, the Cypress team published a post called "In-test" vs "out-of-test" accessibility automation that goes into the tradeoffs in detail.

Resources

The code examples in this article use a weather app I built for testing. If you want to go deeper on Cypress, my book Ultimate Web Automation Testing with Cypress covers the framework end-to-end.

Find me on LinkedIn.