cypress-axe for accessibility - Framework Patterns

Framework Mode - cypress-axe for accessibility

Folder Structure

my-cypress-project/
├── cypress/
│   ├── e2e/                  # Test specs
│   │   └── accessibility.spec.js
│   ├── support/              # Support commands and setup
│   │   ├── commands.js       # Custom commands including axe injection
│   │   └── e2e.js            # Global setup for tests
│   └── fixtures/             # Test data files
├── cypress.config.js         # Cypress configuration
├── package.json              # Project dependencies and scripts
└── README.md
    

Test Framework Layers

• Test Specs (cypress/e2e/): Contains accessibility test files using cypress-axe commands.
• Support Layer (cypress/support/): Holds custom commands to inject and run axe-core accessibility checks.
• Fixtures: Static test data if needed for accessibility scenarios.
• Configuration: Central place to set base URL, viewport, and environment variables.
• Node Modules & Scripts: Manage dependencies like cypress and cypress-axe.

Configuration Patterns

Use cypress.config.js to define:

• Base URL: The website address to test accessibility on.
• Environment Variables: For example, CYPRESS_baseUrl or credentials if needed.
• Viewport Settings: To test accessibility on different screen sizes.
• Setup in cypress/support/e2e.js: Import cypress-axe and add commands to inject axe before tests run.

Example snippet in cypress/support/e2e.js:

import 'cypress-axe';

Cypress.Commands.add('injectAxe', () => {
  cy.injectAxe();
});

Cypress.Commands.add('checkA11y', (context = null, options = null, violationCallback = null) => {
  cy.checkA11y(context, options, violationCallback);
});

Test Reporting and CI/CD Integration

• Use Cypress built-in test runner reports for pass/fail results.
• Integrate with CI tools (GitHub Actions, Jenkins, GitLab CI) to run accessibility tests on pull requests.
• Fail builds if accessibility violations are detected to enforce quality.
• Optionally, use plugins like mochawesome for detailed HTML reports.
• Log accessibility violations clearly in test output for easy debugging.

Best Practices

• Inject axe-core on every page: Always run cy.injectAxe() before accessibility checks to ensure axe is loaded.
• Run accessibility checks on meaningful page states: Test after page load and after dynamic content changes.
• Use context selectors: Limit checks to specific page areas to speed tests and focus on relevant parts.
• Fail tests on violations: Use custom callbacks to log violations and fail tests to catch issues early.
• Keep tests maintainable: Organize accessibility tests separately or alongside functional tests for clarity.

Self Check

Where in this folder structure would you add a new custom command to check accessibility on a modal dialog?

Key Result

Organize Cypress tests with cypress-axe by layering test specs, support commands for axe injection, and configuration for environment control.

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