cypress-axe for accessibility

Introduction

We use cypress-axe to check if websites are easy for everyone to use, including people with disabilities. It helps find problems that make websites hard to read or navigate.

When you want to make sure your website works well for people using screen readers.

Before launching a website to catch accessibility issues early.

When you add new features and want to keep your site accessible.

To test if color choices have enough contrast for easy reading.

When you want to follow accessibility laws or guidelines.

Syntax

Cypress

import 'cypress-axe';

cy.injectAxe();
cy.checkA11y();

First, you import cypress-axe to add accessibility commands to Cypress.

Use cy.injectAxe() to add the accessibility testing tool to your page.

Use cy.checkA11y() to run the accessibility checks and see results.

Examples

Visit a page, add axe, then check accessibility on the whole page.

Cypress

cy.visit('https://example.com');
cy.injectAxe();
cy.checkA11y();

Check accessibility only inside the element with class 'main-content'.

Cypress

cy.checkA11y('.main-content');

Run accessibility checks only for specific WCAG rules.

Cypress

cy.checkA11y(null, {
  runOnly: ['wcag2a', 'wcag2aa']
});

Run checks and handle results with a callback function.

Cypress

cy.checkA11y(null, null, (violations) => {
  // custom handling of violations
  expect(violations.length).to.equal(0);
});

Sample Program

This simple HTML page has a heading and a button. We can use cypress-axe to check if it meets accessibility standards.

Cypress

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Accessibility Test</title>
</head>
<body>
  <header>
    <h1>Welcome to Our Site</h1>
  </header>
  <main>
    <button id="clickMe">Click Me</button>
  </main>
</body>
</html>

Important Notes

Always run cy.injectAxe() after cy.visit() to load axe on the page.

You can focus checks on specific parts of the page to save time.

Use the browser's DevTools console to see detailed accessibility reports.

Summary

cypress-axe helps find accessibility problems automatically during tests.

Inject axe into your page with cy.injectAxe() before checking.

Use cy.checkA11y() to run accessibility checks and get results.

Practice

1. What is the main purpose of using cypress-axe in Cypress tests?

easy

A. To generate random test data for forms

B. To speed up the loading time of web pages

C. To style elements dynamically during tests

D. To automatically find accessibility problems on web pages during tests

Solution

1. Step 1: Understand the role of cypress-axe

   cypress-axe is a tool that integrates axe accessibility checks into Cypress tests.

2. Step 2: Identify what it helps with

   It helps find accessibility issues automatically during test runs to improve web accessibility.

3. Final Answer:

   To automatically find accessibility problems on web pages during tests -> Option D

4. Quick Check:

   cypress-axe = accessibility problem detection [OK]

Hint: Remember cypress-axe finds accessibility issues automatically [OK]

Common Mistakes:

• Thinking it speeds up page loading
• Confusing it with styling tools
• Assuming it generates test data

2. Which command correctly injects axe into the page before running accessibility checks in Cypress?

easy

A. cy.runAxe()

B. cy.loadAxe()

C. cy.injectAxe()

D. cy.startAxe()

Solution

1. Step 1: Recall the cypress-axe setup command

   The official command to inject axe into the page is cy.injectAxe().

2. Step 2: Verify other options

   Other options like cy.runAxe(), cy.loadAxe(), and cy.startAxe() are not valid Cypress commands for this purpose.

3. Final Answer:

   cy.injectAxe() -> Option C

4. Quick Check:

   Inject axe = cy.injectAxe() [OK]

Hint: Use cy.injectAxe() to add axe before checks [OK]

Common Mistakes:

• Using cy.runAxe() instead of cy.injectAxe()
• Confusing command names
• Forgetting to inject axe before checking

3. Given the following Cypress test code snippet, what will cy.checkA11y() do?

cy.visit('/home')
cy.injectAxe()
cy.checkA11y()

medium

A. Run accessibility checks on the entire page and report any violations

B. Reload the page and ignore accessibility

C. Only check the header element for accessibility

D. Throw an error because cy.checkA11y() needs arguments

Solution

1. Step 1: Understand the code sequence

   The code visits the page, injects axe, then runs cy.checkA11y() without arguments.

2. Step 2: Know default behavior of cy.checkA11y()

   Without arguments, cy.checkA11y() runs accessibility checks on the whole page and reports violations.

3. Final Answer:

   Run accessibility checks on the entire page and report any violations -> Option A

4. Quick Check:

   cy.checkA11y() default = full page check [OK]

Hint: cy.checkA11y() without args checks whole page [OK]

Common Mistakes:

• Thinking it only checks part of the page
• Assuming it throws error without args
• Confusing it with page reload

4. You wrote this Cypress test:

cy.visit('/dashboard')
cy.checkA11y()

But the accessibility check does not run and no errors appear. What is missing?

medium

A. You forgot to call cy.injectAxe() before cy.checkA11y()

B. You need to add cy.wait() before cy.checkA11y()

C. You must pass a selector to cy.checkA11y()

D. You should use cy.runAxe() instead of cy.checkA11y()

Solution

1. Step 1: Identify missing axe injection

   Before running accessibility checks, axe must be injected with cy.injectAxe().

2. Step 2: Confirm correct command usage

   Without injection, cy.checkA11y() does not run properly and silently fails.

3. Final Answer:

   You forgot to call cy.injectAxe() before cy.checkA11y() -> Option A

4. Quick Check:

   Inject axe first = cy.injectAxe() [OK]

Hint: Always inject axe before checking accessibility [OK]

Common Mistakes:

• Skipping cy.injectAxe()
• Adding unnecessary cy.wait()
• Passing selector when not needed
• Using wrong command cy.runAxe()

5. You want to check accessibility only on the main content area with id main-content. Which code snippet correctly does this using cypress-axe?

hard

A. cy.checkA11y()
cy.injectAxe('#main-content')

B. cy.injectAxe()
cy.checkA11y('#main-content')

C. cy.injectAxe('#main-content')
cy.checkA11y()

D. cy.checkA11y('#main-content')
cy.injectAxe()

Solution

1. Step 1: Inject axe before checking

   First, call cy.injectAxe() without arguments to add axe to the page.

2. Step 2: Run checkA11y with selector

   Then call cy.checkA11y('#main-content') to check accessibility only inside that element.

3. Final Answer:

   cy.injectAxe() followed by cy.checkA11y('#main-content') -> Option B

4. Quick Check:

   Inject first, then check with selector [OK]

Hint: Inject axe first, then check with selector string [OK]

Common Mistakes:

• Calling checkA11y before injectAxe
• Passing selector to injectAxe
• Not injecting axe at all
• Calling injectAxe after checkA11y