Accessibility Checker for Cypress
Cypress plugin for automated accessibility testing.
The Cypress-accessibility-checker is a wrapper of the accessibility-checker in the Cypress environment.
The deployed package can be downloaded and installed from NPM.
This plugin is a Cypress flavor of the NodeJS version of accessibility-checker which is also available on NPM.
The plugin works by injecting the automated accessibility-checker testing into Cypress, a next-generation front-end testing tool built for the modern web and scanning the page in context.
Please see the Usage section below for more details.
This package is a supporting component of the IBM Equal Access Toolkit.
The Toolkit provides the tools and guidance to create experiences that are delightful for people of all abilities.
The guidance is organized by phase, such as Plan, Design, Develop, and Verify, and explains how to integrate this automated testing tool into the Verify phase.
The Toolkit is a major part of the accessibility information and applications at ibm.com/able.
See the Packages for test automation in the Wiki for an overview.
* Node Version 22
* Cypress 13 or 15 from cypress.io
Install the package as a devDependency.
``bash`
npm install cypress-accessibility-checker --save-dev
The configuration for the plugin is driven by a configuration file called .achecker.yml that you will need to put in the same directory as your cypress.json file. See details on the syntax of this file here.
There are two setup steps you must complete in order for the Cypress tests to be able to use the commands.
In the Cypress config for your project, require the plugin and then register it with Cypress.
`js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
on('task', {
accessibilityChecker: require('cypress-accessibility-checker/plugin')
});
}
}
})
`
In the cypress/support/e2e.js file located in your project, add the following import statement. This will import the accessibility checker commands and register them with Cypress.
`js`
import 'cypress-accessibility-checker';
If you do not want to include cypress-accessibility-checker globally, you may instead add this import statement to every test file in which it is used.
The commands map directly to the description of the APIs located in the accessibility-checker/src/README. The names of the APIs within Cypress are just slightly different so they are globally unique in the Cypress namespace.
The typical use case will be to get the accessibility compliance of a document and then assert the accessibility compliance against the configuration that is defined as part of the .achecker.yml file and any baselines that are defined. An example of how this looks is below:
`bash`
// Retrieves the compliance of the document then checks the results against the defined settings.
// If there are issues when compared to the defined settings, it will fail the Cypress test.
cy.getCompliance('my scan').assertCompliance()
Examples of how to use each of the APIs below can be found in the achecker.js test file located here.
- cy.getCompliance(label)
- Similar to in the reference API above.report
- Returned data (defined here) will only contain the object.cy.getCompliance(cyObj, label)
-
- Similar to in the reference API above, using the passed cy object (typically obtained via cy.document).report
- Returned data (defined here) will only contain the object.cy.assertCompliance(failOnError?: boolean)
-
- If is set to false, this will not fail your test. This is useful for testing what needs to be fixed without failing the test. By default, this command will fail your test unless you specify false here.cy.getDiffResults(label)
-
-
-
-
-
Chain the commands similar to other Cypress commands. For example, cy.getCompliance('my-label').assertCompliance() will get the compliance report of the document and then assert there are no violations or that it matches up with a baseline of the same label.
Review the cypress-accessibility-checker/boilerplates/README and see examples.
Baselines are a helpful feature of cypress-accessibility-checker that can also be used in this Cypress wrapper. The concept involves capturing a scan result as a _baseline_ so that future scans will pass if they match the _baseline_. If they differ, then the test will fail.
Many boilerplate examples include _baselines_.
This feature is useful for issues that have been determined to be of the following:
- false positives determined to be ignored
- Needs review issues resolved
- issues scheduled to be fixed later
- new regression issues captured
See the Baseline basics in the Wiki for an overview.
There is a suite of tests located in the test/ directory which execute each of the added Cypress commands. You can run this test suite by doing one of the following:
* npm test: Executes the tests in a headless environmentnpm run test:open
* : Opens the Cypress interactive mode. Run npm run test:start-http in order for the tests to work.
The plugin does not need to be built to be used. However, there is a package script to group things for NPM.
`bash`
npm install
npm run package:npm or npm run package:zip
If you think you've found a bug, have questions or suggestions, open a GitHub Issue, tagged with cypress-accessibility-checker.
If you are an IBM employee, feel free to ask questions in the IBM internal Slack channel #accessibility-at-ibm`.
This package uses IBM Telemetry to collect de-identified and anonymized metrics data. By installing this package as a dependency you are agreeing to telemetry collection. To opt out, see Opting out of IBM Telemetry data collection. For more information on the data being collected, please see the IBM Telemetry documentation.
