Introduction

In today’s digital age, web accessibility is more important than ever. Ensuring that your website is accessible to everyone, including people with disabilities, is not just a legal requirement but also a moral obligation. We have integrated automated accessibility testing into our development workflow using Cypress and cypress-axe. This article will walk you through our approach, highlighting the key features and benefits of our framework.

Why Web Accessibility Matters

Web accessibility ensures that all users, regardless of their abilities, can navigate and interact with your website. It enhances user experience, broadens your audience, and helps you comply with legal standards such as the Americans with Disabilities Act (ADA) and the Web Content Accessibility Guidelines (WCAG).

Our Approach to Automated Accessibility Testing

To streamline the process of identifying and fixing accessibility issues, we have enhanced Cypress with custom commands that leverage the power of cypress-axe. This integration allows us to automatically check web pages for accessibility issues during our testing process.

Github Repo: mbatra5/Eurowings_FlightSearch at accessibility-axe

Key features of the framework

Automated Accessibility Checks:

By integrating cypress-axe into our Cypress tests, we can automatically scan web pages for accessibility issues. This ensures that potential problems are identified early in the development process.

Custom Commands:

We have created several custom commands to make accessibility testing easier and more flexible. These commands allow us to target specific elements, exclude known problematic areas, and focus on critical issues.

Accessibility Logger:

Our framework includes an advanced Accessibility Logger that enhances the visibility and understanding of accessibility issues detected during testing.

Flexible Configuration:

Offers configurable options to tailor accessibility checks according to specific needs.

Integration with BDD & Cucumber:

Human-Readable Tests: Write tests in plain language using Gherkin syntax, making them easy to understand and manage.
Collaborative Approach: Encourage collaboration between developers, testers, and non-technical stakeholders by using BDD practices.

How It Works

Custom Commands

Here are some of the custom commands we have created:

Setup Command:

Command: setupA11y
Description: Sets up the necessary configuration for accessibility testing.
Usage: Prepares the page for accessibility testing by injecting Axe and configuring it.
cy.setupA11y();

Check All Impacts:

Command: checkA11yAllImpacts
Description: Checks the entire page or a specific element for all types of accessibility issues.
Usage: Can be used to perform a comprehensive accessibility check on the whole page or a specific part of it.
cy.checkA11yAllImpacts(null, terminalLog);

Check Specific Locator:

Command: checkA11yForLocator
Description: Checks a specific element on the page for accessibility issues.
Usage: Useful for targeting specific elements that might have accessibility concerns.
cy.checkA11yForLocator('.example-class');

Exclude Tags:

Command: checkA11yExcludeTags
Description: Checks a parent element but excludes certain child elements from the check.
Usage: Helps focus on specific areas while ignoring known problematic elements.
cy.checkA11yExcludeTags('._parent-element', ['img'], terminalLog);

Best Practices:

Command: checkA11yBestPractices
Description: Checks the page for best practice accessibility guidelines.
Usage: Ensures the page follows general accessibility best practices.
cy.checkA11yBestPractices(null, terminalLog);

Exclude Elements:

Command: checkA11yExcludeElements
Description: Checks the entire page but excludes specific HTML elements from the results.
Usage: Allows excluding certain elements from the scan if they are known to have issues.
cy.checkA11yExcludeElements(['img'], terminalLog);

P1 and P2 Issues:

Command: checkA11yP1P2
Description: Focuses on critical and serious accessibility issues.
Usage: Prioritizes checking for the most impactful accessibility problems.
cy.checkA11yP1P2(terminalLog);

XPath Support:

Command: checkA11yForXPath
Description: Checks an element found by XPath.
Usage: Supports scanning elements identified by XPath selectors for more flexible element targeting.
cy.checkA11yForXPath('//div[@class="example-class"]', terminalLog);

XPath Exclude Tags:

Command: checkA11yForXPathExcludeTags
Description: Checks an element found by XPath but excludes certain tags.
Usage: Allows excluding specific tags within an XPath-selected element.
cy.checkA11yForXPathExcludeTags('//div[@class="example-class"]', ['img'], terminalLog);

Run Specific Rules:

Command: checkA11yForRules
Description: Runs only specific rules by their IDs.
Usage: Useful for focusing on particular accessibility rules relevant to your project.
cy.checkA11yForRules(['color-contrast', 'image-alt'], terminalLog);

Exclude Specific Rules:

Command: checkA11yExcludeRules
Description: Excludes specific rules by their IDs.
Usage: Helps exclude known rules that are not relevant for the current test.
cy.checkA11yExcludeRules(['color-contrast', 'valid-lang'], terminalLog);

Setup

To get started, we installed necessary libraries like cypress-axe and cypress-xpath. We then configured Cypress plugins to support custom logging tasks and created support files to define custom commands and logging functions.

Dependencies

Here are the key dependencies used in our framework:

Cypress: The core testing framework.
cypress-axe: Integrates the axe-core accessibility testing library with Cypress.
cypress-xpath: Adds XPath support to Cypress.
cypress-cucumber-preprocessor: Enables BDD-style testing with Cucumber.

Installation

To set up the project, clone the repository from GitHub and run the following command to install all dependencies:

npm install

Here’s a simple example of how to use our custom commands in a test:

Visit the Page: Navigate to the page you want to test.
Set Up Accessibility Testing: Prepare the page for accessibility testing.
Run Accessibility Checks: Use our custom commands to run the tests and log any issues.

Scripting

Feature: Web Accessibility Tests

Feature: Web Accessibility Tests

Scenario Outline: Verify all WCAG Violations
  Given I am on the "<url>" page
  And Verify all Accessibility Violations

Scenario Outline: Verify P1,P2 WCAG Violations
  Given I am on the "<url>" page
  And Verify only P1, P2 issues

Examples:
  | url                |
  | https://google.com |
  | https://amazon.in  |
  | https://agoda.com  | 
  | https://bing.com   |
  | https://cypress.io |

Step Definition: wcag.ts

/// <reference types="Cypress" />
import { Given, When, Then, And } from 'cypress-cucumber-preprocessor/steps';
import { terminalLog } from '../../../support/accessibilityLogger'

Given('I am on the {string} page', (url) => {
    cy.visit(url);
    cy.setupA11y(); // Set up accessibility testing configuration after visiting the URL
  });

And('Verify all Accessibility Violations', () => {
  cy.checkA11yAllImpacts(null, terminalLog);
});

Given('I am on the {string} page', (url) => {
  cy.visit(url);
  cy.setupA11y(); // Set up accessibility testing configuration after visiting the URL
});

And('Verify only P1, P2 issues', () => {
  cy.checkA11yP1P2(terminalLog);
});

Execution

The tests can be executed in cypress runner

npx cypress open

If accessibility violations are detected, the test will fail, and an entry labeled “A11Y ERROR!” will appear in the command log for each violation type identified, positioned above the failed assertion. Clicking on these entries will display detailed information about the error in the DevTools console.

or they can be executed in a headless mode where the script to be run is already added in ‘package.json’

npm run test:report

Accessibility Logger — Technical Details

The Accessibility Logger is a custom utility integrated into our Cypress framework to enhance the visibility and understanding of accessibility issues detected during testing. Here’s a detailed look at its functionality:

How It Logs

The logger captures accessibility violations detected by axe-core and logs them in a structured format. It uses Cypress tasks to output logs to both the terminal and the browser console.

Where It Logs

Terminal: Logs are output to the terminal running Cypress tests, making it easy to review issues in CI environments or local development setups.

Browser Console: Logs are also output to the browser console, providing immediate feedback while running tests interactively in the Cypress Test Runner.

What It Logs

The logger captures and logs the following information for each accessibility violation:

Type of Issue: The specific type of accessibility issue detected (e.g., color contrast, missing alt text).

Impact Level: The severity of the issue (e.g., minor, moderate, serious, critical).

Description: A brief description of the issue.

Guideline Information: References to the relevant WCAG guidelines that are not being met.

Affected Elements: The number of HTML elements affected by the issue.
Additionally, the logger provides:

URL Logging: The URL of the page being tested is logged once at the top, summarizing the total number of violations.

Summary and Details: The logger provides a summary of the total number of violations as well as detailed information for each issue, ensuring you have all the context needed to address accessibility problems.

References:

https://github.com/component-driven/cypress-axe

https://www.deque.com/axe/core-documentation/api-documentation/

Ensuring Web Accessibility with Cypress