cypress-axe for accessibility - Build an Automation Script

Check homepage accessibility using cypress-axe

Preconditions (3)

Step 1: Open the homepage URL in the browser

Step 2: Inject the axe-core accessibility testing library into the page

Step 3: Run accessibility checks on the entire page

Step 4: Collect and analyze accessibility violations

✅ Expected Result: No accessibility violations are found on the homepage

Automation Requirements - Cypress with cypress-axe plugin

Assertions Needed:

Assert that there are zero accessibility violations after running axe check

Best Practices:

Use cy.injectAxe() to inject axe-core before running checks

Use cy.checkA11y() to run accessibility checks

Use semantic selectors or data attributes for targeting elements if needed

Run accessibility checks on meaningful page sections or entire page

Fail test if any accessibility violations are detected

Automated Solution

Cypress

/// <reference types="cypress" />
import 'cypress-axe';

describe('Homepage Accessibility Test', () => {
  beforeEach(() => {
    cy.visit('https://example.com');
    cy.injectAxe();
  });

  it('Has no detectable accessibility violations on load', () => {
    cy.checkA11y(null, null, (violations) => {
      expect(violations).to.have.length(0);
    });
  });
});

This test script uses Cypress with the cypress-axe plugin to check accessibility on the homepage.

Import and setup: We import 'cypress-axe' to add accessibility commands.

beforeEach: Visits the homepage URL and injects the axe-core library into the page so accessibility checks can run.

Test case: Runs cy.checkA11y() on the entire page (null selector means whole page). The callback receives any violations found.

Assertion: We assert that the violations array length is zero, meaning no accessibility issues were detected.

This approach ensures the test fails if any accessibility problems exist, helping maintain an accessible website.

Common Mistakes - 4 Pitfalls

Not calling cy.injectAxe() before cy.checkA11y()

Using hardcoded CSS selectors that are brittle for targeting elements

Ignoring accessibility violations by not asserting on the violations array

Running accessibility checks before the page is fully loaded

Bonus Challenge

Now add data-driven testing to check accessibility on three different pages: homepage, about page, and contact page

Show Hint

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