axe-core with Cypress — Complete Guide

In this tutorial, you will learn about axe. We cover key concepts, practical examples, and best practices to help you master this topic.

Cypress-axe integrates axe-core Accessibility rules into Cypress end-to-end tests, allowing you to write assertions like cy.checkA11y() that scan the current page state and fail the test if WCAG violations are found.

What You'll Learn

You will install and configure cypress-axe, write accessibility test assertions for pages and components, filter violations by severity, and integrate checks into existing Cypress test suites.

Why It Matters

End-to-end tests already verify that pages render and interactions work. Adding accessibility assertions to those tests means you catch accessibility regressions alongside functional regressions -- with zero additional test maintenance overhead.

Real-World Use

A team has 200 Cypress tests covering their app. They add cy.checkA11y() to the page-load test for each route. Now every test automatically verifies accessibility, catching issues like a new component added without proper ARIA labels.

Cypress-axe Integration Flow

flowchart TD
  A[Cypress Test Suite] --> B[cy.visit(page)]
  B --> C[Wait for content]
  C --> D[cy.injectAxe()]
  D --> E[cy.checkA11y()]
  E --> F{Violations?}
  F -->|Yes| G[Test Fails]
  F -->|No| H[Test Passes]
  G --> I[Review violations]
  I --> J[Fix and re-run]

Installation and Setup

Install cypress-axe and configure it in your Cypress support file. The plugin adds cy.injectAxe() and cy.checkA11y() commands.

npm install --save-dev cypress-axe

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

// Basic accessibility test
describe('Homepage accessibility', () => {
  beforeEach(() => {
    cy.visit('/');
    cy.injectAxe();
  });

  it('has no WCAG violations', () => {
    cy.checkA11y();
  });

  it('has no critical violations', () => {
    cy.checkA11y(null, {
      includedImpacts: ['critical']
    });
  });
});

You can filter violations by WCAG level, impact, and exclude known issues.

// Test with specific WCAG tags and exclusions
cy.checkA11y(
  'main', // Context: only check the main area
  {
    runOnly: {
      type: 'tag',
      values: ['wcag2a', 'wcag2aa']
    }
  },
  (violations) => {
    // Custom logging
    cy.task('log', `${violations.length} violations found`);
  }
);

Common Mistakes

• Forgetting to call cy.injectAxe() before cy.checkA11y()
• Checking accessibility before the page finishes rendering
• Not excluding known, documented issues from new violations
• Running checks only on the default state without testing interactive states
• Using overly broad context selectors that include third-party content
• Not configuring the impact level to match project standards
• Ignoring violations in test output without reviewing them

Practice and Challenge

Practice 1: Install cypress-axe in a Cypress project and add a test for the homepage. Practice 2: Write a test that checks only critical violations. Practice 3: Filter accessibility checks to exclude a known issue using exclude. Practice 4: Write a test that checks accessibility after clicking a button. Practice 5: Configure cypress-axe to check only WCAG AA rules.

Challenge: Create a Cypress custom command cy.checkAllPages() that visits every route in your app, injects axe, and runs accessibility checks on each route, collecting all violations into a single report.

FAQ

Mini Project

Create a Cypress test suite that visits five key pages of an e-commerce site (homepage, product listing, product detail, cart, checkout), checks accessibility on each page, and also checks the checkout page in both empty and populated cart states.

What's Next

Lighthouse Audit covers running comprehensive Lighthouse accessibility audits.