Forem: Vitaly Skadorva

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.