wick-a11y
v2.5.0TypeScript
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 t
0/weekUpdated 4 months agoMITUnpacked: 71.1 MB
Published by Sebastian Clavijo Suero
npm install wick-a11ywick-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.
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!"
- "WICK-A11Y "Chapter" 1.2.1 - Voice Support: The Accessibility Cypress Plugin that Talks More Than John Wick in His Movies"
- WICK-A11Y 1.4.0: Not Everything Needs to Fail a Test!"
Or the videos:
- "WICK-A11Y ACCESSIBILITY PLUGIN VIDEO TUTORIAL (English)"
- "Cypress - Accesibilidad con WICK-A11Y (Español) - Playlist"
---
MAIN FEATURES
- Comprehensive Accessibility Analysis: Leverages axe-core® and cypress-axe plugin for thorough accessibility checks. Axe-core®
- 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.
- 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)_.
- Two types of reports: _(NEW in v2.5.0)_
- Detailed - Stylish card layout with an enhanced screenshot view featuring interactive elements for each accessibility issue, enabling improved visualization and exploration (the HTML includes embedded JavaScript code). _(NEW in v2.4.0)_
- Basic - Compact and minimalistic layout, with screenshots without interactive elements (smaller file size, only HTML5 and CSS3 code). _(NEW in v2.5.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
- TABLE OF CONTENT
- INSTALATION
- COMPATIBILITY
- Cypress v15+
- Cypress v14
- Cypress v12 and v13
- CONFIGURATION
- API REFERENCE
- cy.checkAccessibility(context, options)
- Options
- Context
- USAGE EXAMPLES
- RESULTS PRESENTATION
- Summary of Violations
- Violation Details in Browser Console from Cypress Log
- Violation Details in Tooltip when Hovering over a DOM Element on the Page
- Accessibility Voice
- Suite Level
- Test Level
- Violation Type Level
- DOM Element Level in Cypress Log
- DOM Element Level in the Web Page
- Custom Styles Based on Severity
- HTML Reports
- Reports Location
- Reports Content
- Report Types
- Detailed Report (Default)
- Basic Report
- Terminal Report
- KNOWN LIMITATIONS
- LICENSE
- CONTRIBUTING
- CHANGELOG
- EXTERNAL REFERENCES
INSTALATION
``sh`
npm install wick-a11y --save-dev
COMPATIBILITY
$3
- Use wick-a11y v2.2.0 or greater+
- Relies on cypress-axe (≥ 1.7.0) and axe-core® for accessibility analysis.
$3
- Use wick-a11y v2.0.0
- Relies on cypress-axe (≥ 1.5.0) and axe-core® for accessibility analysis.
- ⚠️ Not officially tested with Cypress v14.0.0 to v14.0.2 (but should work).
$3
- Use wick-a11y v1.4.0 or earlier
- Relies on cypress-axe (≥ 1.5.0) and axe-core® for accessibility analysis.
- If you want to install wick-a11y v1.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, a detailed HTML report of accessibility violations is generated whenever issues are detected during the analysis. This behavior can be modified by setting the Cypress environment variable generateReport.detailed
Acepted values:
- – Generates a detailed HTML accessibility report (default). Also accepted true.basic
- – Generates a simplified, minimalistic HTML accessibility report.none
- – Disables report generation entirely. Also accepted false.
This can be overridden by using the generateReport option when calling the checkAccessibility() command.
5. 👉 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 configure a Cypress 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 file`
json`
{
"enableAccessibilityVoice": true
}
- Providing it as a command line argument in the terminal when opening the Cypress runner.`
shell`
npx cypress open --env enableAccessibilityVoice=true
API REFERENCE
$3
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, Axe-core® GitHub, and cypress-axe NPM.
- 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'].'input, .container, [data-cy="submission"]'
E.g.2 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"]'
- : (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 html report with the accessibility violations.true
Options:
- or 'detailed': Default option. Generate a detailed html report with Cards design.'basic'
- : Generate a basic html report (also smaller file size).false
- or 'none': Do not generate html report of violations
⚠️ IMPORTANT: If the checkAccessibility() command includes the generateReport option, it will override the value of the generateReport environment variable.
- 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: '🛠️' }
}
- : (optional) From CYPRESS-AXE - Number of times to retry the check if there are initial findings.0
Default: .interval
- : (optional) From CYPRESS-AXE - Number of milliseconds to wait between retries.1000
Default: .runOnly
- : (optional) From axe-core® - List to specify which rules are executed.['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice']
Default: .rules
> ⚠️ 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.
- : (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.'v2'
E.g. .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.['violations', 'incomplete', 'inapplicable']
E.g. .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®.true
Default: .ancestry
- : (optional) From axe-core® - Return CSS selector for elements, with all the element's ancestors.false
Default: .xpath
- : (optional) From axe-core® - Return xpath selectors for elements.false
Default: .absolutePaths
- : (optional) From axe-core® - Use absolute paths when creating element selectors.false
Default: .iframes
- : (optional) From axe-core® - Tell axe to run inside iframes.true
Default: .elementRef
- : (optional) From axe-core® - Return element references in addition to the target.false
Default: .frameWaitTime
- : (optional) From axe-core® - How long (in milliseconds) axe waits for a response from embedded frames before timing out.60000
Default: .preload
- : (optional) From axe-core® - Any additional assets to preload before running rules.true
Default: .performanceTimer
- : (optional) From axe-core® - Log rule performance metrics to the console.false
Default: .pingWaitTime
- : (optional) From axe-core® - Time in milliseconds before axe-core® considers a frame unresponsive.500
Default: .
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 }, () => {
// Also generateReport: false
cy.checkAccessibility(null, { generateReport: 'none', includedImpacts: ['critical', 'serious', 'moderate', 'minor'] });
});
it('Basic report generation', { defaultCommandTimeout: 15000 }, () => {
cy.checkAccessibility(null, { generateReport: 'basic', includedImpacts: ['critical', 'serious', 'moderate', 'minor'] });
});
it('Detailed report generation', { defaultCommandTimeout: 15000 }, () => {
// Default is 'detailed' report, so it can be omited generateReport option
cy.checkAccessibility(null, { generateReport: 'detailed', 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.
$3
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.
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
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
$3
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.
$3
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.
$3
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:
Same custom styles shown in the HTML report:
$3
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.
#### 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
#### 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
#### 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
#### 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
#### 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
$3
Wick-a11y HTML accessibility reports are mostly WCAG 2.2 AAA compliant, supports full keyboard navigation and it is mobile responsive.
#### Reports Location
By default, all 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 ---
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.
#### Reports Content
Any wick-a11y HTML accessibility report consists of three sections
1. Report Summary
At the beginning of the HTML report, you will find the Report Summary, which includes:
- Test summary: spec name, test name, page URL, and generation timestamp
- Accessibility configuration: context, tabs, and rules
- Violations: total counts by severity
2. Accessibility Violations Details
The Accessibility Violations Details section lists all detected accessibility issues, grouped by severity (Critical, Serious, Moderate, Minor).
Each group includes the affected DOM elements, along with detailed information and guidance on how to fix the issues.
3. Accessibility Violations ScreenShot
At the end of the report, there is a screenshot section that highlights the elements affected by accessibility issues, color-coded by severity.
This section also includes a disclaimer referencing axe-core®.
#### Report Types
There are two type of reports:
1. Detailed
2. Basic
You can also skip generating HTML accessibility reports (even when accessibility issues are detected) by setting the Cypress environment variable generateReport to none or false.
Alternatively, you can pass the generateReport option with the value 'none' or false directly to the checkAccessibility() command.
When both are provided, the command option takes precedence over the environment variable.
E.g.
`javascript`
it('Disable report for default analysis', { defaultCommandTimeout: 15000 }, () => {
cy.checkAccessibility(null, { generateReport: 'none'});
});
> ⚠️ If no accessibility issues are found, no report will be generated.
> ✔️ 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.
##### Detailed Report (Default)
A visually rich report presented in a stylish card layout, featuring an enhanced screenshot view with interactive elements for each accessibility issue. Detailed is the default report.
Accessibility issues are grouped by severity, with each group providing the rule description, impact, and the affected DOM elements.
For each affected element, you can expand its card to view detailed guidance on how to fix the accessibility issue.
This format enables better visualization and exploration of accessibility issues within the page.
It includes convenient controls to expand or collapse cards, scroll to the screenshot view, and return to the top of the report.
This report type includes embedded JavaScript for interactivity.
_HTML Report Detailed - Desktop_
_HTML Report Detailed - Mobile_
_HTML Report Violation Details_
!HTML Report Violation Details
_HTML Report Detailed - Interactive Screenshot_
!HTML Report Detailed Interactive Screenshot
##### Basic Report
A simplified and minimalistic HTML report with a clean layout and static screenshots (no interactive elements).
It provides the same essential data -violation summaries, issue details, and fix recommendations- but in a lighter format with a smaller file size, using only HTML5 and CSS3.
Ideal for CI/CD pipelines or environments where interactivity is not required.
_HTML Report Basic Desktop_
$3
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 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 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
$3
- Added Basic, minimalistic HTML report option.
- Fixed issue where tooltips did not close correctly when resizing the browser window.
$3
- Enhanced HTML report with screenshots supporting interactive elements for each accessibility issue.
$3
- Adds accessibility analysis for WCAG 2.2 levels A, AA, and AAA.
- New improved HTML report (Detailed): 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.
$3
- Supports Cypress v15.
- This v2.2.0 is not compatible with Cypress ≤v14.
$3
- 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).
- Fix issue when a test does not include acccessibility checking and it does not fail.
$3
- 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).
$3
- wick-a11y plugin migrated to Cypress v14.0.3.
- Resolve dependency tree issues when installing wick-a11y in a Cypress v14.0.3 project.
$3
- 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).
$3
- Added types for command checkAccessibility.
- Limit size of image in HTML report to 1920px width (contribution by James Wadley).
- Use of Cypress 13.17.0 to run package tests.
$3
- Fix issue in creating HTML reports caused by isNodeList() left behind in the refactor into multiple source files.
$3
- Fix issue with voice buttons not showing for a test when retries.openMode:0 in cypress.config.js.
$3
- 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.
$3
- Fix issue with accessibilityFolder configuration parameter when missing char / at the end..gitignore`.
- Add axe-core® to the source code and documentation to be compliant with Deque trademark.
- Created
$3
- 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.
$3
- 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.
$3
- Fix typo in README.md.
$3
- 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
- Cypress.io Official Documentation — Accessibility Testing
- Cypress.io Official Blog — Mark Noonan: Open Source Accessibility Plugins in Cypress
- TestGuild Testing Tool Matcher — Cypress Resource: wick-a11y
- testdev.tools — Hand-Picked Software Testing Tools & Resources: wick-a11y
- digitala11y.com — Open Source Accessibility Testing Tools Roundup
- Joan Esquivel Montero — Video: Cypress Accessibility Testing powered by WICK-A11Y, and Spanish version
- Ioan Solderea — Video: European Accessibility Act 2025: Compliance Deadline Nears – How Cypress.io Can Save Your Business
- Ioan Solderea — Video: Wick A11y – Cypress Plugin for Automated Accessibility Checks
- Gleb Bahmutov — Cypress Tips Newsletter: Sept 2024 - WICK-A11Y plugin with voice support, and Dec 2024 - Sebastian Clavijo's WICK-A11Y
- Dawid Dylowicz — Newsletter: Software Testing Weekly Issue 235
- Pritesh Usadadiya — Newsletter: Software Testing Notes Issue 141
- James Wadley — Blog: Let's talk about wick-a11y…
- and many more...