Accessibility testing with CodeceptJS, Playwright and Axe
Accessibility testing plays a crucial role in ensuring that digital products are inclusive and usable for all users, including those with disabilities. While many software development teams leverage QA and end to end automation to build their digital products, accessibility testing step is commonly overlooked from the automation pipelines.
CodeceptJS, a modern test automation framework, can be integrated with Playwright and Axe accessibility tool to gain valuable insights into the accessibility status of your web application or website efficiently.
Accessibility Testing
Accessibility testing involves evaluating a web application or website to ensure it is usable by individuals with disabilities, including those with visual, auditory, cognitive, or motor impairments. The goal of accessibility testing is to identify and address any issues that may hinder a user’s ability to access and navigate the site effectively.
Playwright
Playwright is a robust testing framework that offers dependable end-to-end and cross-browser testing capabilities for web applications. It is compatible with major web browsers like Chromium, Firefox, and WebKit. Playwright provides a unified API for interacting with web browsers, allowing tests to be written once and executed across multiple browsers without the need for separate code for each browser.
CodeceptJS
CodeceptJS is a contemporary test automation framework that integrates with various testing frameworks, including Playwright, to facilitate end-to-end testing of web, mobile, and desktop applications (including Electron.js). It offers a user-friendly syntax and a robust set of features for creating and running automated tests.
Axe
Axe is a powerful and efficient tool for accessibility testing that is built on top of the popular accessibility testing library, axe-core. Axe offers a suite of tools for full coverage testing and compliance needs. There are multiple ways to use Axe, including the axe DevTools, axe Auditor, and axe Monitor.
Install dependencies
Add axe-playwright npm dependency into the existing CodeceptJS test automation project configured with the Playwright helper.
npm install axe-playwright --save-devaxe-playwright provides custom commands for Playwright to run accessibility (a11y) checks using Axe.
Add Axe integration
Create a custom steps file CustomSteps.ts and include it within CodeceptJS config in codecept.conf.ts.
// codecept.conf.ts
export const config: CodeceptJS.MainConfig = {
// ...
include: {
I: './CustomSteps',
}
// ...
}As CodeceptJS provides the ability to abstract commonly used actions under an actor object, we could write a checkA11y function that will be accessible at any point in the test scenario.
// CustomSteps.ts
import { injectAxe, checkA11y } from 'axe-playwright'
export = function() {
return actor({
checkA11y: function () {
this.usePlaywrightTo('Run accessability tests', async ({ page }) => {
await injectAxe(page)
await checkA11y(page)
})
},
})
}CodeceptJS provides the ability to call the underlying helper API, which is Playwright in this case. This can be done by calling usePlaywrightTo method.
Run accessibility tests
Now we can inject Axe in any point in our end to end test to scan for accessibility issues. Calling checkA11y function will break the test in case accessibility issues are found.
I.amOnPage('https://alphagov.github.io/accessibility-tool-audit/test-cases.html')
I.checkA11y()Here we are using Accessibility audit test cases page from UK Government Digital Service.
A sample output from Axe will list accessibility issues including issue type, its impact on the user, a description and the number of occurrences on the analysed page.
Use CodeceptJS Accessibility helper
To access more Axe features, include codeceptjs-a11y-helper in your CodeceptJS project.
npm install codeceptjs-a11y-helper --save-devUpdate the configuration in codecept.conf.ts.
{
helpers: {
A11yHelper: {
require: 'codeceptjs-a11y-helper',
},
},
}If you require more detailed configuration, it is possible to include accessibility standards in the configuration as well.
{
helpers: {
A11yHelper: {
require: 'codeceptjs-a11y-helper',
axeOptions: {
runOnly: {
values: [
'wcag2a', 'wcag2aa', 'wcag2aaa', 'wcag21a', 'wcag21aa', 'wcag22aa',
'best-practice', 'wcag***', 'ACT', 'experimental', 'cat.*'
],
},
},
},
},
}Remember to regenerate CodeceptJS TypeScript definitions. TypeScript definitions provide autocomplete functionality in Visual Studio Code and other IDEs.
npx codeceptjs defRun the newly provided method from the helper to verify accessibility and generate a report.
await I.runA11yCheck()With every method run, a HTML report with accessibility violations is generated and saved in your output folder.
Sample E2E Test --
Renders and asserts a sample web page
I am on page "https://alphagov.github.io/accessibility-tool-audit/test-cases.html"
I run a11y check
HTML report was saved into the following directory /codeceptjs-playwright-typescript-boilerplate/output/accessibility-audit/1698381370375_accessibility-audit.html
✔ OK in 14846ms
You can attach accessibility report as an artefact to your CI/CD pipeline or deploy it to static asset hosting platforms such as GitHub Pages.
Summary
Accessibility testing is essential for ensuring that digital products are accessible to all users, including those with disabilities. Unfortunately, it is often overlooked in automation pipelines despite the use of QA and end-to-end automation in software development.
Modern end-to-end testing frameworks, such as CodeceptJS and Playwright, along with the Axe accessibility tool, can assist in integrating accessibility testing into the QA automation pipeline. This integration enables software engineers to gain accessibility insights for their websites and web applications.
Source code
The approach described in this article is implemented in CodeceptJS Playwright Typescript Boilerplate and available in Bear Plus GitHub space.
