https://github.com/sclavijosuero/wick-a11y

A Cypress plugin for configurable accessibility analysis supporting WCAG 2.2 (A–AAA). It reports detailed violations in the Cypress log, provides visual feedback in the runner, and generates a severity-based HTML report with per-violation details, fix guidance, and annotated screenshots. Built on axe-core and cypress-axe for comprehensive analysis.
https://github.com/sclavijosuero/wick-a11y

a11y a11y-report a11y-testing accessibility accessibility-report accessibility-testing cypress cypress-io plugin

Last synced: 8 months ago
JSON representation

A Cypress plugin for configurable accessibility analysis supporting WCAG 2.2 (A–AAA). It reports detailed violations in the Cypress log, provides visual feedback in the runner, and generates a severity-based HTML report with per-violation details, fix guidance, and annotated screenshots. Built on axe-core and cypress-axe for comprehensive analysis.

• Host: GitHub
• URL: https://github.com/sclavijosuero/wick-a11y
• Owner: sclavijosuero
• License: mit
• Created: 2024-06-30T21:21:44.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2025-10-05T03:22:10.000Z (8 months ago)
• Last Synced: 2025-10-05T03:48:10.371Z (8 months ago)
• Topics: a11y, a11y-report, a11y-testing, accessibility, accessibility-report, accessibility-testing, cypress, cypress-io, plugin
• Language: JavaScript
• Homepage:
• Size: 67 MB
• Stars: 48
• Watchers: 1
• Forks: 6
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# wick-a11y

**wick-a11y** is a Cypress plugin for configurable accessibility analysis supporting WCAG 2.2 (A–AAA).

It provides a detailed list of violations in the Cypress log, visual feedback directly in the Cypress runner, and generates a comprehensive, severity-based HTML report that includes per-violation details, fix guidance, and a screenshot with interactive elements for each accessibility issue. The plugin uses axe-core and cypress-axe to deliver comprehensive accessibility testing.

![wick-a11y Overview](/images/full-overview.gif)

For a detailed guide on setting up and using this plugin to maximize its benefits, please refer to my articles:

  - ["WICK-A11Y Cypress Plugin: Your Unstoppable Ally for Smashing Accessibility Barriers, Cool as John Wick!"](https://dev.to/sebastianclavijo/wick-a11y-cypress-plugin-your-unstoppable-ally-for-smashing-accessibility-barriers-cool-as-john-wick-280a)

  - ["WICK-A11Y "Chapter" 1.2.1 - Voice Support: The Accessibility Cypress Plugin that Talks More Than John Wick in His Movies"](https://dev.to/sebastianclavijo/wick-a11y-v121-voice-the-accessibility-cypress-plugin-that-talks-more-than-john-wick-in-his-movies-8c8)

  - [WICK-A11Y 1.4.0: Not Everything Needs to Fail a Test!"](https://dev.to/sebastianclavijo/wick-a11y-140-not-everything-needs-to-fail-a-test-1pe5)

Or the videos:

  - ["WICK-A11Y ACCESSIBILITY PLUGIN VIDEO TUTORIAL (English)"](https://www.youtube.com/watch?v=WpdrXU-6xzc)

  - ["Cypress - Accesibilidad con WICK-A11Y (Español) - Playlist"](https://www.youtube.com/playlist?list=PLJZz46d_HRpjDPUPirWAaP2NXRFX-xxGd)

---

## MAIN FEATURES

- **Comprehensive Accessibility Analysis**: Leverages axe-core® and cypress-axe plugin for thorough accessibility checks. Axe-core®  is a trademark of Deque Systems, Inc.  in the US and other countries.

  

- **Cypress Command**: Use the custom command `cy.checkAccessibility()` to run checks smoothly.

- **Configurable**:

  - Customize which impact levels (severities), rules, and guidelines to include.

  - Configure specific impact levels to determine which should fail the test and which should act only as warnings, providing detailed feedback.

- **Summary of Violations**:  Provides a summary for each test in the Cypress Log, detailing accessibility violations categorized by their severity.

  

- **Detailed Violation Information**:

  - Displays detailed accessibility violation information in both the Cypress log and the browser console.

  - Visually highlights affected DOM elements on the page, enclosing them in color-coded boxes based on severity.

  - When available, uses `data-cy`, `data-testid`, `data-test`, `data-qa`, and `data-test-id` selectors to identify accessibility violations. **_(NEW in v2.3.0)_**

- **Custom Styling**: Supports custom styling for accessibility issues based on severity level at the test level.

- **Interactive Console**:

  - **From the Cypress Log**: Hover over a violation to highlight the affected DOM element on the page. Click it to view detailed issue information in the browser console.

  - **From the Cypress Runner**: Hover over any DOM element with a violation to highlight it visually and display a tooltip with the violation details.

- **HTML Reports**:

  - **Out of the box**, ready to use with no additional setup.

  - Comprehensive severity-based report of accessibility issues, including detailed information and clear fix recommendations.

  - **Enhanced screenshot view** featuring **interactive elements** for each accessibility issue, allowing improved visualization and exploration. **_(NEW in v2.4.0)_**.

  - **WCAG 2.2 AAA**-compliant reports, with **full keyboard navigation**. **_(NEW in v2.3.0)_**.

  - **Fully responsive design**, optimized for mobile devices with improved layout and usability. **_(NEW in v2.3.0)_**.

- **Terminal Reports**: Generates terminal reports in a clear tabular format, including details of each violation and guidance on how to fix them.

- **Voice Support**: Provides audible information for accessibility issues at the suite level, test level, violation type level, and DOM element level, helping users identify issues through voice feedback.

- **Cypress v15+ Support**:  Fully supported in Cypress v15.0.0 or greater **_(NEW in v2.2.0)_**.

> ✔️ **Before launching the accessibility analysis, ensure what you want to analyze is fully rendered on the page.**

> 

> ✔️ **The plugin analyzes DOM elements that are visible in the browser viewport as per the axe-core® plugin (it will not include hidden elements).**

---

## TABLE OF CONTENT

- [MAIN FEATURES](#main-features)

- [TABLE OF CONTENT](#table-of-content)

- [INSTALATION](#instalation)

- [COMPATIBILITY](#compatibility)

  - [Cypress v15+](#cypress-v15)

  - [Cypress v14](#cypress-v14)

  - [Cypress v12 and v13](#cypress-v12-and-v13)

- [CONFIGURATION](#configuration)

- [API REFERENCE](#api-reference)

  - [cy.checkAccessibility(context, options)](#cycheckaccessibilitycontext-options)

- [USAGE EXAMPLES](#usage-examples)

- [RESULTS PRESENTATION](#results-presentation)

  - [Summary of Violations](#summary-of-violations)

  - [Violation Details in Browser Console from Cypress Log](#violation-details-in-browser-console-from-cypress-log)

  - [Violation Details in Tooltip when Hovering over a DOM Element on the Page](#violation-details-in-tooltip-when-hovering-over-a-dom-element-on-the-page)

  - [Accessibility Voice](#accessibility-voice)

    - [Accessibility Voice for Analysis at Suite Level in Cypress Log](#accessibility-voice-for-analysis-at-suite-level-in-cypress-log)

    - [Accessibility Voice for Analysis at Test Level in Cypress Log](#accessibility-voice-for-analysis-at-test-level-in-cypress-log)

    - [Accessibility Voice for Analysis at Violation Type Level in Cypress Log](#accessibility-voice-for-analysis-at-violation-type-level-in-cypress-log)

    - [Accessibility Voice for Analysis at DOM Element Level in Cypress Log](#accessibility-voice-for-analysis-at-dom-element-level-in-cypress-log)

    - [Accessibility Voice for Analysis at DOM Element Level in the Web Page](#accessibility-voice-for-analysis-at-dom-element-level-in-the-web-page)

  - [Custom Styles Based on Severity](#custom-styles-based-on-severity)

  - [HTML Report](#html-report)

    - [Report Summary](#report-summary)

    - [Accessibility Violations Details](#accessibility-violations-details)

    - [Interactive Accessibility Violations ScreenShot](#interactive-accessibility-violations-screenshot)

  - [Terminal Report](#terminal-report)

- [KNOWN LIMITATIONS](#known-limitations)

- [LICENSE](#license)

- [CONTRIBUTING](#contributing)

- [CHANGELOG](#changelog)

- [EXTERNAL REFERENCES](#external-references)

## INSTALATION

```sh

npm install wick-a11y --save-dev

```

## COMPATIBILITY 

### Cypress v15+

- Use wick-a11y *v*2.2.0 or greater+

- Relies on cypress-axe (≥ 1.7.0) and axe-core® for accessibility analysis.

### Cypress v14

- Use wick-a11y *v*2.0.0

- Relies on cypress-axe (≥ 1.5.0) and axe-core® for accessibility analysis.

-  ⚠️ **Not officially tested** with Cypress *v*14.0.0 to *v*14.0.2 (but should work).

### Cypress v12 and v13

- Use  wick-a11y *v*1.4.0 or earlier

- Relies on cypress-axe (≥ 1.5.0) and axe-core® for accessibility analysis.

- If you want to install wick-a11y *v*1.4.0 or earlier in a Cypress 14.0.3 project you will need to use the `--force` option:

   ```sh

   npm install wick-a11y --save-dev --force

   ```

## CONFIGURATION

1. First, in your **`cypress.config.js`** file import `wick-a11y/accessibility-tasks`, and add the line `addAccessibilityTasks(on)` within the **`setupNodeEvents`** function,  to include the accessibility tasks:

```javascript

const { defineConfig } = require("cypress");

// Import the accessibility tasks from wick-a11y plugin

const addAccessibilityTasks = require('wick-a11y/accessibility-tasks');

module.exports = defineConfig({

  e2e: {

    setupNodeEvents(on, config) {

      // Add accessibility tasks

      addAccessibilityTasks(on);

    },

    

    // ... rest of the configuration

  },

});

```

2. Then import the custom commands in your **test file** or your **`cypress/support/e2e.js`** file:

```javascript

import 'wick-a11y';

```

3. 👉 Accessibility HTML reports will be generated in the folder **`cypress/accessibility`** by default. This folder can be changed by including the configuration parameter **`accessibilityFolder`** in **`cypress.config.js`**.

```javascript

module.exports = defineConfig({

  // [...]

  accessibilityFolder: 'cypress/your-accessibility-reports-folder',

  // [...]

});

```

4. 👉 By default, the voice feature is disabled. To enable it, set the Cypress environment variable **`enableAccessibilityVoice`** to **`true`**. This will only take effect when you execute tests in the Cypress runner (`npx cypress open`). You can enable the voice feature by setting this environment variable in three different ways:

    - Including it within the `env` property in the **`cypress.config.js`** file

    

      ```javascript

      module.exports = defineConfig({

            // [...]

            env: {

                  enableAccessibilityVoice: true

            }

            // [...]

      });

      ```

    - Including it in the **`cypress.env.json`** file

    

      ```json

      {

            "enableAccessibilityVoice": true

      }

      ```

    - Providing it as a command line argument `--env` in the terminal when opening the Cypress runner.

    

      ```shell

      npx cypress open --env enableAccessibilityVoice=true

      ```

## API REFERENCE

### cy.checkAccessibility(context, options)

Cypress custom command to check the accessibility of a given context using axe-core®. Only considers DOM elements that are visible on the screen. For details on parameters and options, refer to [Axe-core® Documentation](https://www.deque.com/axe/core-documentation/api-documentation/), [Axe-core® GitHub](https://github.com/dequelabs/axe-core), and [cypress-axe NPM](https://www.npmjs.com/package/cypress-axe).

- **`context`**: (optional) Defines the scope of the analysis. Can be a CSS Selector, a DOM Element, or an Object.

  When **context** is an Object, it could have the properties:

  

  - **`exclude`**: (optional) *From axe-core®* - Elements that should not be tested. Format: CSS Selector or Array of CSS selectors.

  

    E.g.1 `'button'` equivalent to `['button']`.

    

    E.g.2 `'input, .container, [data-cy="submission"]'` equivalent to `['input', '.container', '[data-cy="submission"]']`.

  - **`include`**: (optional) *From axe-core®* - Elements that should be tested. Format: CSS Selector or Array of CSS selectors.

  

    E.g. `'[data-cy="header"]'`

   

  - **`fromFrames`**: (optional) *From axe-core®* - An object with a fromFrames property to specify frames that should be tested.

   

  - **`fromShadowDom`**: (optional) *From axe-core®* - An object with a fromShadowDom property to specify shadow DOM elements that should be tested.

   

- **`options`**: (optional) Object with options to configure the accessibility check.

  

  - **`generateReport`**: (optional) *From WICK-A11Y* - Generate a detailed report.

  

    Default: `true`.

  - **`includedImpacts`**: (optional) *From CYPRESS-AXE* - List of impact levels to include in the accessibility analysis that would make the analysis to fail. Map to impact levels in violations, where possible impact level values are "critical", "serious", "moderate", or "minor".

  

    Default: `['critical', 'serious']`.

    Examples:

      - `{ includedImpacts: ['critical', 'serious'] }` - Analysis will fail with critical or serious violations. No other severities will be considered.

      - `{ includedImpacts: ['critical', 'serious', 'moderate', 'minor'] }` - Analysis will fail with critical, serious, moderate or minor violations.

  - **`onlyWarnImpacts`**: (optional) *From WICK-A11Y* - List of impact levels to include in the accessibility analysis that will provide a warning, but not to fail. Map to impact levels in violations, where possible impact level values are "critical", "serious", "moderate", or "minor".

  

    Default: `[]`.

    Examples:

      - `{ includedImpacts: ['critical', 'serious'], onlyWarnImpacts: ['moderate', 'minor'] }` - Analysis will fail with critical and serious violations, and will just provide a warning for moderate and minor violations.

      - `{ includedImpacts: [], onlyWarnImpacts: ['critical', 'serious'] }` - Analysis will provide a warning for critical and serious violations, but will not fail. No other severities will be considered.

      - `{ includedImpacts: [], onlyWarnImpacts: ['critical', 'serious', 'moderate', 'minor'] }` - Analysis will provide a warning for critical, serious, moderate and minor violations, but will not fail.

      - `{ includedImpacts: ['critical', 'serious', 'moderate'], onlyWarnImpacts: ['moderate', 'minor'] }` - If there is overlapping between includedImpacts and onlyWarnImpacts, the includedImpacts configuration will have precedence, so in this case 'moderate' violations will make the test to fail even when also included in the warning list.

  - **`impactStyling`**: (optional) *From WICK-A11Y* - An object with an entry for each impact level you would like to override the plugin defaults ('critical', 'serious', 'moderate', 'minor').

  

    Each impact level entry may have two properties: 'icon', which specifies the icon to use for that type of violation in the Cypress runner, and 'style', which specifies the CSS style to apply to the HTML element bounding box showing the violation on the page.

    The styles passed in this option will override the default ones used by the plugin.

  

    Default styles:

     ```javascript

     {

        critical: { icon: '🟥', style: 'fill: #DE071B; fill-opacity: 0; stroke: #DE071B; stroke-width: 8; stroke-linejoin: round; stroke-dasharray: 5 2;' },

        serious: { icon: '🟧', style: 'fill: #FFA66A; fill-opacity: 0; stroke: #FFA66A; stroke-width: 8; stroke-linejoin: round; stroke-dasharray: 5 2;' },

        moderate: { icon: '🟨', style: 'fill: #ECDE05; fill-opacity: 0; stroke: #ECDE05; stroke-width: 8; stroke-linejoin: round; stroke-dasharray: 5 2;' },

       minor: { icon: '🟦', style: 'fill: #4598FF; fill-opacity: 0; stroke: #4598FF; stroke-width: 8; stroke-linejoin: round; stroke-dasharray: 5 2;' },

       fixme: { icon: '🛠️' }

     }

     ```

   

  - **`retries`**: (optional) *From CYPRESS-AXE* - Number of times to retry the check if there are initial findings.

  

    Default: `0`.

   

  - **`interval`**: (optional) *From CYPRESS-AXE* - Number of milliseconds to wait between retries.

  

    Default: `1000`.

   

  - **`runOnly`**: (optional) *From axe-core®* - List to specify which rules are executed.

  

    Default: `['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice']`.

   

    > ⚠️ **IMPORTANT:**  You must include all the rules (tags) that you want to execute in your analysis in this list. 

    > 

    > For example, if you want to run WCAG 2.2 AAA and all the previous versions of that standard (wcag2a, wcag2aa, wcag2aaa, wcag21a, wcag21aa, wcag21aaa, wcag22a, wcag22aa, , wcag22aaa), you need to list them explicitly. Otherwise, only the rules specific to WCAG 2.2 AAA will be executed.

   

  - **`rules`**: (optional) *From axe-core®* - Enable or disable rules using the enabled property.

    E.g. `{ 'color-contrast': { enabled: false }, 'valid-lang': { enabled: false } }`.

   

  - **`reporter`**: (optional) *From axe-core®* - Which reporter to use.

    

    E.g. `'v2'`.

   

  - **`resultTypes`**: (optional) *From axe-core®* - Limit which result types are processed and aggregated. This can be useful for improving performance on very large or complicated pages when you are only interested in certain types of results.

    

    E.g. `['violations', 'incomplete', 'inapplicable']`.

   

  - **`selectors`**: (optional) *From axe-core® and wick-a11y* - Return CSS selector for elements optimized for readability. If data-* test atributes are found () it will return them, other wise will return the selectors provided by axe-core®.

  

    Default: `true`.

   

  - **`ancestry`**: (optional) *From axe-core®* - Return CSS selector for elements, with all the element's ancestors.

  

    Default: `false`.

   

  - **`xpath`**: (optional) *From axe-core®* - Return xpath selectors for elements.

  

    Default: `false`.

   

  - **`absolutePaths`**: (optional) *From axe-core®* - Use absolute paths when creating element selectors.

  

    Default: `false`.

   

  - **`iframes`**: (optional) *From axe-core®* - Tell axe to run inside iframes.

  

    Default: `true`.

   

  - **`elementRef`**: (optional) *From axe-core®* - Return element references in addition to the target.

  

    Default: `false`.

   

  - **`frameWaitTime`**: (optional) *From axe-core®* - How long (in milliseconds) axe waits for a response from embedded frames before timing out.

  

    Default: `60000`.

   

  - **`preload`**: (optional) *From axe-core®* - Any additional assets to preload before running rules.

  

    Default: `true`.

   

  - **`performanceTimer`**: (optional) *From axe-core®* - Log rule performance metrics to the console.

  

    Default: `false`.

   

  - **`pingWaitTime`**: (optional) *From axe-core®* - Time in milliseconds before axe-core® considers a frame unresponsive.

  

    Default: `500`.

Example: Disable report, include only critical, serious, and moderate violations, and apply only the standards WCAG 2.0A, WCAG 2.0AA, and Best Practices.

```javascript

cy.checkAccessibility(null, {

  generateReport: false,

  includedImpacts: ['critical', 'serious', 'moderate'],

  runOnly: ['wcag2a', 'wcag2aa', 'best-practice']

});

```

Example: Use custom styles for accessibility violations with serious, moderate, and minor severity levels, and use a custom icon for "fixme". For critical violations, the default style will be used.

```javascript

const customImpactStyling = {

  serious:  { icon: '🟢', style: 'fill: #42C600; fill-opacity: 0; stroke: #42C600; stroke-width: 7;' },

  moderate: { icon: '🟣', style: 'fill: #886DE7; fill-opacity: 0.3; stroke: #886DE7; stroke-width: 6; stroke-dasharray: 5,3;' },

  minor:    { style: 'fill: #4598FF; fill-opacity: 0; stroke: #4598FF; stroke-width: 14; ' },

  fixme:    { icon: '🪓' }

 }

  cy.checkAccessibility(null, { impactStyling: customImpactStyling, includedImpacts: ['critical', 'serious', 'moderate', 'minor'] })

```

## USAGE EXAMPLES

**Basic Usage**

In this basic usage example, the `cy.checkAccessibility()` function is called without parameters, so it will perform an accessibility analysis with the default configuration:

- Analyze the entire page document.

- Include elements with impact levels 'critical' and 'serious'.

- Run the rules for WCAG 2.0 Level A, WCAG 2.0 Level AA, WCAG 2.1 Level A, WCAG 2.1 Level AA, and best practices.

- Generate an HTML report for the identified violations.

> ⚠️ Before launching the accessibility analysis, ensure that what you want to analyze is fully rendered on the page. Only DOM elements that are visible in the browser viewport will be considered, as per the axe-core® plugin (hidden elements will be ignored).**

>

> ⚠️ **Accessibility analysis can take some time, so it is recommended to increase the _`defaultCommandTimeout`_ when running an accessibility test. You can configure this timeout either directly when defining the test or in your _`cypress.config.js`_ file.**

```javascript

describe('Accessibility Test', () => {

  beforeEach(() => {

    cy.visit('http://example.com');

  });

  it('should check accessibility of the page', { defaultCommandTimeout: 15000 }, () => {

    cy.checkAccessibility();

  });

});

```

**Specify Context and Options Usage**

```javascript

describe('Accessibility Tests', { tags: ['@accessibility'] }, () => {

  beforeEach(() => {

    cy.visit('http://example.com');

  });

  it('Default analysis', { defaultCommandTimeout: 15000 }, () => {

    cy.checkAccessibility();

  });

  it('All severity levels make test to fail', { defaultCommandTimeout: 15000 }, () => {

    cy.checkAccessibility(null, { includedImpacts: ['critical', 'serious', 'moderate', 'minor'] });

  });

  it('Severities "critical" and "serious" fail test and severities "moderate" and "minor" provide warnings', { defaultCommandTimeout: 15000 }, () => {

    cy.checkAccessibility(null, { includedImpacts: ['critical', 'serious'] , onlyWarnImpacts: ['moderate', 'minor'] });

  });

  it('All severity levels provide warnings (test not to fail)', { defaultCommandTimeout: 15000 }, () => {

    cy.checkAccessibility(null, { includedImpacts: [], onlyWarnImpacts: ['critical', 'serious', 'moderate', 'minor'] });

  });

  it('Disable rules "contrast" and "valid-lang"', { defaultCommandTimeout: 15000 }, () => {

    cy.checkAccessibility(null, { rules: { 'color-contrast': { enabled: false }, 'valid-lang': { enabled: false } } });

  });

  it('Disable report generation', { defaultCommandTimeout: 15000 }, () => {

    cy.checkAccessibility(null, { generateReport: false, includedImpacts: ['critical', 'serious', 'moderate', 'minor'] });

  });

  it('Provide context as CSS selector and only best-practice', { defaultCommandTimeout: 15000 }, () => {

    cy.checkAccessibility(['div[role="banner"]', 'ul'], { includedImpacts: ['critical', 'serious', 'moderate', 'minor'], runOnly: ['best-practice'] });

  });

  it('Provide context as HTML Element and all levels of severity', { defaultCommandTimeout: 15000 }, () => {

    cy.document().then((doc) => {

      cy.checkAccessibility(doc.getElementById('my-navigation'), { includedImpacts: ['critical', 'serious', 'moderate', 'minor'] });

    });

  });

  it('Provide context as HTML NodeList', { defaultCommandTimeout: 15000 }, () => {

    cy.document().then((doc) => {

      cy.checkAccessibility(doc.querySelectorAll('div[role="banner"], ul'), { includedImpacts: ['critical', 'serious', 'moderate', 'minor'] });

    });

  });

  it('Provide context as "exclude" and "include"', { defaultCommandTimeout: 15000 }, () => {

    cy.checkAccessibility({ exclude: 'li', include: 'li:nth-child(2)' }, { includedImpacts: ['critical', 'serious', 'moderate', 'minor'] });

  });

  it('Custom colors by severity', {defaultCommandTimeout: 15000}, () => {

    const customImpactStyling = {

        critical: { icon: '🔴', style: 'fill: #DE071B; fill-opacity: 0; stroke: #DE071B; stroke-width: 10;' },

        serious:  { icon: '🟢', style: 'fill: #42C600; fill-opacity: 0; stroke: #42C600; stroke-width: 7;' },

        moderate: { icon: '🟣', style: 'fill: #886DE7; fill-opacity: 0.3; stroke: #886DE7; stroke-width: 6; stroke-dasharray: 5,3;' },

        minor:    { icon: '🔵', style: 'fill: #4598FF; fill-opacity: 0; stroke: #4598FF; stroke-width: 14; ' },

        fixme:    { icon: '🪓' }

    }

    cy.checkAccessibility(null, { impactStyling: customImpactStyling, includedImpacts: ['critical', 'serious', 'moderate', 'minor'] })

  });

});

```

## RESULTS PRESENTATION

All the accessibility violations are shown in the Cypress log, ordered by severity, and are also graphically highlighted on the page, enclosed in a bounding box colored according to the severity level.

Styles by default: Critical 🟥, Serious 🟧, Moderate 🟨, Minor 🟦

If there are any violations for the selected rules used in the analysis, the test will fail.

![Runner Results](/images/runner-results.png)

### Summary of Violations

For each test, it shows a summary of the accessibility violations categorized by their severity in the Cypress Log at the end of the test.

![Violations Summary](/images/violations-summary.png)

If the analysis was configured to consider accessibility issues as either a violation (failing the test) or a warning, they will be distinguished as such in the summary.

![Violations Summary with Warnings](/images/violations-summary-warnings.png)

By clicking on one of the severity groups in the summary, the details for all the violations of that severity type will be shown in the browser console.

![Summary Details per Severity Type](/images/summary-details-severity.png)

### Violation Details in Browser Console from Cypress Log

To identify, in the page, which HTML element is affected by an accessibility violation, mouseover the specific violation in the Cypress log, and that element will be highlighted on the page. To know the details about the accessibility issue, click on the violation in the Cypress log and those details will be shown in the browser console.

![Runner Console](/images/runner-console-new.png)

### Violation Details in Tooltip when Hovering over a DOM Element on the Page

When hovering over a specific DOM element with a violation on the page in the Cypress runner, the element will be highlighted graphically, and a tooltip will appear showing the violation information. This feature allows you to quickly identify and understand accessibility issues directly on the page, providing an immediate and intuitive way to address them.

![Runner Screen](/images/runner-screen.png)

### Accessibility Voice

The wick-a11y plugin provides users with audible information about the accessibility analysis results executed in the suite. Audible analysis is available at all levels through the Cypress Log and by clicking affected DOM elements directly on the web page in the Cypress runner. Accessibility voice is only available when tests are run in the Cypress runner (`npx cypress open`), and the Cypress environment variable `enableAccessibilityVoice` is set to `true`.

This feature is particularly useful for users who rely on auditory information to enhance their understanding and streamline the process of accessibility testing and remediation.

The analysis at a specific level in the Cypress Log can be heard by clicking the play button beside it. While the voice is playing, the user can pause, resume, and stop the voice analysis using the respective buttons.

![Voice Buttons](/images/voice-buttons.png)

#### Accessibility Voice for Analysis at Suite Level in Cypress Log

The accessibility voice feature at the suite level in the Cypress Log provides audible feedback that summarizes the accessibility analysis for the entire test suite. This includes:

- Total number of tests run

- Number of tests passed

- Number of tests failed due to accessibility violations

- Number of tests failed for other reasons

- Number of tests skipped or pending

![Voice Suite Level](/images/voice-suite.png)

[Watch the video](/videos/README.md#accessibility-voice-for-analysis-at-suite-level-in-cypress-log "Accessibility Voice for Analysis at Suite Level in Cypress Log")

#### Accessibility Voice for Analysis at Test Level in Cypress Log

The accessibility voice feature at the test level in the Cypress Log provides audible feedback that summarizes the accessibility analysis for each individual test. This includes:

- Total number of accessibility violations

- Number of critical violations

- Number of serious violations

- Number of moderate violations

- Number of minor violations

![Voice Test Level](/images/voice-test.png)

[Watch the video](/videos/README.md#accessibility-voice-for-analysis-at-test-level-in-cypress-log "Accessibility Voice for Analysis at Test Level in Cypress Log")

#### Accessibility Voice for Analysis at Violation Type Level in Cypress Log

The accessibility voice feature at the violation type level in the Cypress Log provides audible feedback that includes:

- The number of DOM elements found with that violation

- The severity of the violation

- A description of the violation

![Voice Violation Type Level](/images/voice-violation.png)

[Watch the video](/videos/README.md#accessibility-voice-for-analysis-at-violation-type-level-in-cypress-log "Accessibility Voice for Analysis at Violation Type Level in Cypress Log")

#### Accessibility Voice for Analysis at DOM Element Level in Cypress Log

The accessibility voice feature at the DOM element level in the Cypress Log provides audible feedback that includes:

- The selector for the element

- The severity of the violation

- A description of the violation

- A summary of the actions needed to fix the issue

![Voice DOM Element Level](/images/voice-dom-element.png)

[Watch the video](/videos/README.md#accessibility-voice-for-analysis-at-dom-element-level-in-cypress-log "Accessibility Voice for Analysis at DOM Element Level in Cypress Log")

#### Accessibility Voice for Analysis at DOM Element Level in the Web Page

The wick-a11y plugin also provides accessibility voice for a DOM element by clicking directly on the colored box representing the violation in the web page. To cancel the playback, the user can simply click outside the web page area. The audible feedback provides the following information:

- The selector for the element

- The severity of the violation

- A description of the violation

- A summary of the actions needed to fix the issue

![Voice DOM Element Web Page](/images/voice-dom-element-page.png)

[Watch the video](/videos/README.md#accessibility-voice-for-analysis-at-dom-element-level-in-the-web-page "Accessibility Voice for Analysis at DOM Element Level in the Web Page")

### Custom Styles Based on Severity

It is possible to configure styles for the different types of violation severity beyond the default red, orange, yellow, and blue.

Configured custom styles are displayed in the Cypress runner:

![Configured custom styles](images/runner-custom-styles.png)

Same custom styles shown in the HTML report:

### HTML Report

The HTML accessibility report is mostly **WCAG 2.2 AAA compliant**, supports **full keyboard navigation** and it is **mobile responsive**.

When the option **`generateReport`** is true (which is the default setting), an HTML report with all the accessibility violation details will be generated. By default, accessibility HTML reports are created in the `cypress/accessibility` folder. You can customize this location by setting the `accessibilityFolder` parameter in your `cypress.config.js` configuration file.

For each test that checks accessibility using the `cy.checkAccessibility()` command, a directory will be created in the accessibility folder.

The directory will be named in the following format:

**`Accessibility Report ---  ---  ()`**

![Accessibility Folder](/images/accessibility-folder.png)

Within the newly created test folder, you will find two files:

- `Accessibility Report.html` - This file contains the complete accessibility report, detailing the violations for that specific test.

- `Accessibility Issues Image.png` - This file includes a screenshot of the issues for visual reference.

The image file is also referenced within the HTML report.

![Accessibility Files](/images/accessibility-files.png)

At the top of the report, it is displayed a card with a **Report Summary**. Accessibility issues are grouped into cards and ordered by severity. All cards in the report are expandable and collapsible.

At the end of the report, a **screenshot** of the page is provided, showing violations boxed and color-coded by severity. Each issue includes **interactive elements** that display detailed information and fix guidance when clicked.

Also, the report is _mobile responsive_ by stacking the cards, mostly _WCAG 2.2 AAA compliant_ and fully supports _keyboard navigation_.

[Watch the video](/videos/README.md#wick-a11y-accessibility-report "Accessibility Report")

> ✔️ **Note:** The HTML accessibility report generated by the plugin complies with all severity levels—critical, serious, moderate, and minor. It also adheres to the tags wcag2a, wcag2aa, wcag2aaa, wcag21a, wcag21aa, wcag21aaa, wcag22a, wcag22aa, wcag22aaa, and best-practice.

**Desktop Layout HTML Report**

![HTML Report Desktop](/images/html-report.png)

**Mobile Layout HTML Report**

![HTML Report Mobile](/images/html-report-mobile.png)

**HTML Report Fully Collapsed**

![HTML Report Fully Collapsed](/images/html-report-collapsed.png)

#### Report Summary

At the beginning of the HTML report, an expandable/collapsible Report Summary section appears. It includes:

  - Test summary: spec name, test name, page URL, and generation timestamp

  - Accessibility configuration: context, tabs, and rules

  - Violations: total counts by severity

For convenience, at the top there are buttons that let you Expand All cards, Collapse All cards, and Scroll to the Screenshot.

![HTML Report Summary](/images/html-report-summary.png)

#### Accessibility Violations Details

The **Accessibility Violations Details** section includes a card for each Severity Level included in the analysis: Critical, Serious, Moderate, and/or Minor.

Within each section, there is a list of violation types for that severity, and for each violation type, a list of the affected DOM elements with details about how to fix the issue.

![HTML Accessibility Violations Details](/images/html-report-violations-details.png)

#### Interactive Accessibility Violations ScreenShot

At the end of the report, there is a section that includes a screenshot showing the elements affected by accessibility issues, color-coded by severity.

The screenshot features an interactive layout that highlights each accessibility issue on hover, and displays a tooltip on click with detailed information about the violation and guidance on how to fix it.

Also this section includes a button to return to the top of the page, and also a disclaimer with a reference to axe-core®.

![HTML Accessibility Violations ScreenShot](/images/html-report-violations-screenshot.png)

### Terminal Report

A tabular report containing all accessibility violation details will be generated in the Terminal. This includes a summary of violations and warnings, categorized by severity level.

## KNOWN LIMITATIONS

- Only allows running one accessibility analysis with the command `cy.checkAccessibility()` per test.

- Only the last test run in the suite allows graphical interaction with the web page.

- When an element is "**Pinned**" in the Cypress Log, the accessibility voice for a DOM element by clicking directly on the colored box representing the violation on the web page is disabled (due to the behavior of the Cypress runner in the interactive page).

- At this moment, it does not flag suspicious violations considered by the AJV validator as inconclusive.

## LICENSE

MIT License. See the [LICENSE](LICENSE) file for more details.

## CONTRIBUTING

First off, thanks for taking the time to contribute!

To contribute, please follow the best practices promoted by GitHub on the [Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project "Contributing to a project") page.

And if you like the project but just don't have the time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:

- Star the project

- Promote it on social media

- Refer this project in your project's readme

- Mention the project at local meetups and tell your friends/colleagues

- Buying me a coffee or contributing to a training session, so I can keep learning and sharing cool stuff with all of you.



Thank you for your support!

## CHANGELOG

### v2.4.0

- Screenshot with interactive elements highlighting accessibility issues.

### v2.3.0

- Adds accessibility analysis for WCAG 2.2 levels A, AA, and AAA.

- Improves HTML report: full mobile responsive, improved usability, full keyboard navigation support, mostly WCAG 2.2 AAA compliant.

- Uses `data-cy`, `data-testid`, `data-test`, `data-qa`, and `data-test-id` selectors for accessibility violations when available.

- Displays accessibility issues in the Cypress Runner UI with dashed outlines by default.

### v2.2.0

- Supports Cypress v15.

- This v2.2.0 is not compatible with Cypress ≤v14.

### v2.1.0

- Supports cypress-axe 1.7.0

- Fix issue of Incorrect Screenshot File Path for Deeply Nested Tests and running specific tests suiteds with `--spec` (contribution by [Peter M Souza Jr](https://github.com/petermsouzajr "Peter M Souza Jr")).

- Fix issue when a test does not include acccessibility checking and it does not fail.

### v2.0.1

- Fix issue of Incorrect Screenshot File Path for Deeply Nested Tests https://github.com/sclavijosuero/wick-a11y/issues/21 (contribution by [Peter M Souza Jr](https://github.com/petermsouzajr "Peter M Souza Jr")).

### v2.0.0

- wick-a11y plugin migrated to Cypress v14.0.3.

- Resolve dependency tree issues when installing wick-a11y in a Cypress v14.0.3 project.

### v1.4.0

- Added option `onlyWarnImpacts` with list of violations severities to include in the analysis to provide a warning, but not to fail.

- Copy violations screenshot to html report folder instead of moving (to add compatibility with Allure reporter).

### v1.3.0

- Added types for command checkAccessibility.

- Limit size of image in HTML report to 1920px width (contribution by [James Wadley](https://github.com/w4dd325 "James Wadley")).

- Use of Cypress 13.17.0 to run package tests.

### v1.2.2

- Fix issue in creating HTML reports caused by isNodeList() left behind in the refactor into multiple source files.

### v1.2.1

- Fix issue with voice buttons not showing for a test when retries.openMode:0 in cypress.config.js.

### v1.2.0

- Added support for voice in the Cypress Log and when clicking on DOM elements with violations on the page.

- Introduced a new summary for each test in the Cypress Log, detailing accessibility violations categorized by their severity.

### v1.1.2

- Fix issue with `accessibilityFolder` configuration parameter when missing char `/` at the end.

- Add axe-core® to the source code and documentation to be compliant with Deque trademark.

- Created `.gitignore`.

### v1.1.1

- Fix issue regarding highlighting violation when hovering in the cypress runner during the analysis screenshot .

- Fix reported issue when multiple retries are enabled https://github.com/sclavijosuero/wick-a11y/issues/2.

### v1.1.0

- Implemented tooltip with violations details when hovering over DOM Element in the Cypress runner.

- Change color highlighted DOM elements from the Cypress log to match color used when hovering.

### v1.0.1

- Fix typo in README.md.

### v1.0.0

- Initial release with core functionalities.

- Comprehensive configuration options for AXE analysis.

- Detailed logging and report generation for accessibility violations.

## EXTERNAL REFERENCES

- [**W3C Org** — Official Web Accessibility Evaluation Tools List](https://www.w3.org/WAI/test-evaluate/tools/list/ "W3C Org — Official Web Accessibility Evaluation Tools List")

- [**Cypress.io Official Documentation** — Accessibility Testing](https://docs.cypress.io/app/guides/accessibility-testing "Cypress.io Official Documentation — Accessibility Testing")

- [**Cypress.io Official Blog** — Mark Noonan: Open Source Accessibility Plugins in Cypress](https://www.cypress.io/blog/open-source-accessibility-plugins-in-cypress "Cypress.io Official Blog — Mark Noonan: Open Source Accessibility Plugins in Cypress")

- [**TestGuild Testing Tool Matcher** — Cypress Resource: wick-a11y](https://testguild.com/tools/cypress "TestGuild Testing Tool Matcher — Cypress Resource: wick-a11y")

- [**testdev.tools** — Hand-Picked Software Testing Tools & Resources: wick-a11y](https://testdev.tools/wick-a11y/ "testdev.tools — Hand-Picked Software Testing Tools & Resources: wick-a11y")

- [**digitala11y.com** — Open Source Accessibility Testing Tools Roundup](https://www.digitala11y.com/open-source-accessibility-tools/ "digitala11y.com — Open Source Accessibility Testing Tools Roundup")

- [**Joan Esquivel Montero**](https://www.linkedin.com/in/joanesquivel/ "Joan Esquivel Montero") — Video: [Cypress Accessibility Testing powered by WICK-A11Y](https://www.youtube.com/watch?v=LVxyJMW6EJw "Cypress Accessibility Testing powered by WICK-A11Y"), and [Spanish version](https://www.youtube.com/watch?v=96Sz2QCXE7I "Spanish version")

- [**Ioan Solderea**](https://www.linkedin.com/in/%F0%9F%95%B5ioan-s-b0928516/ "Ioan Solderea") — Video: [European Accessibility Act 2025: Compliance Deadline Nears – How Cypress.io Can Save Your Business](https://www.youtube.com/watch?v=joP3TNdLjF8 "European Accessibility Act 2025: Compliance Deadline Nears – How Cypress.io Can Save Your Business")

- [**Ioan Solderea**](https://www.linkedin.com/in/%F0%9F%95%B5ioan-s-b0928516/ "Ioan Solderea") — Video: [Wick A11y – Cypress Plugin for Automated Accessibility Checks](https://www.youtube.com/watch?v=joP3TNdLjF8 "Wick A11y – Cypress Plugin for Automated Accessibility Checks")

- [**Gleb Bahmutov**](https://www.linkedin.com/in/bahmutov/ "Gleb Bahmutov") — Cypress Tips Newsletter: [Sept 2024 - WICK-A11Y plugin with voice support](https://cypresstips.substack.com/i/149058474/wick-ay-plugin-with-voice-support "Sept 2024 - WICK-A11Y plugin with voice support"), and [Dec 2024 - Sebastian Clavijo's WICK-A11Y](https://cypresstips.substack.com/i/153579922/sebastian-clavijo-suero "[Dec 2024 - Sebastian Clavijo's WICK-A11Y") 

- [**Dawid Dylowicz**](https://www.linkedin.com/in/dawid-dylowicz/ "Dawid Dylowicz") — Newsletter: [Software Testing Weekly Issue 235](https://softwaretestingweekly.com/issues/235 "Software Testing Weekly Issue 235 ")

- [**Pritesh Usadadiya**](https://www.linkedin.com/company/software-testing-notes/posts/ "Pritesh Usadadiya") — Newsletter: [Software Testing Notes Issue 141](https://softwaretestingnotes.substack.com/p/issue-141-software-testing-notes "Software Testing Notes Issue 141")

- [**James Wadley**](https://www.linkedin.com/in/w4dd325/ "James Wadley") — Blog: [Let's talk about wick-a11y…](https://dev.to/w4dd325/lets-talk-about-wick-a11y-1afa "Let's talk about wick-a11y…")

- and many more...