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.