What is axe-playwright?
The axe-playwright npm package is a tool that integrates the axe-core accessibility testing engine with Playwright, allowing developers to automate accessibility testing for web applications. It helps identify and fix accessibility issues by running axe-core checks within Playwright tests.
What are axe-playwright's main functionalities?
Automated Accessibility Testing
This feature allows you to perform automated accessibility testing on web pages. The code sample demonstrates how to launch a browser using Playwright, navigate to a web page, inject the axe-core library, and run accessibility checks.
const { chromium } = require('playwright');
const { injectAxe, checkA11y } = require('axe-playwright');
(async () => {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await injectAxe(page);
const results = await checkA11y(page);
console.log(results);
await browser.close();
})();
Customizable Accessibility Checks
This feature allows you to customize the accessibility checks by specifying options such as WCAG levels. The code sample shows how to run accessibility checks with specific WCAG tags.
const { chromium } = require('playwright');
const { injectAxe, checkA11y } = require('axe-playwright');
(async () => {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await injectAxe(page);
const options = { runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] } };
const results = await checkA11y(page, null, options);
console.log(results);
await browser.close();
})();
Integration with Playwright Test Runner
This feature allows you to integrate accessibility checks directly into Playwright's test runner. The code sample demonstrates how to write a Playwright test that includes an accessibility check and asserts that there are no violations.
const { test, expect } = require('@playwright/test');
const { injectAxe, checkA11y } = require('axe-playwright');
test('Accessibility test', async ({ page }) => {
await page.goto('https://example.com');
await injectAxe(page);
const results = await checkA11y(page);
expect(results.violations.length).toBe(0);
});
Other packages similar to axe-playwright
axe-core
axe-core is the underlying accessibility testing engine used by axe-playwright. It can be used directly for accessibility testing in various environments, including browser extensions and other automation tools. While axe-playwright integrates axe-core with Playwright, axe-core itself is more versatile and can be used with other testing frameworks.
pa11y
Pa11y is an accessibility testing tool that can be used to run automated accessibility tests on web pages. It provides a command-line interface and can be integrated with various CI/CD pipelines. Compared to axe-playwright, Pa11y is more standalone and does not require Playwright for running tests.
cypress-axe
cypress-axe is a plugin that integrates axe-core with Cypress, another popular end-to-end testing framework. It provides similar functionality to axe-playwright but is designed for use with Cypress instead of Playwright. Both tools offer automated accessibility testing, but they cater to different testing frameworks.
Axe-Playwright
Axe is an accessibility testing engine for websites and other HTML-based user interfaces. This package provides simple axe analyser commands which you can incorporate in your Playwright tests.
Install and configure
Add as a dev dependency:
npm i -D axe-playwright
Install peer dependencies:
npm i -D playwright
NOTE: axe-core is now bundled and doesn't need to be installed as a peer dependency
Add Typings
{
"compilerOptions": {
"types": ["axe-playwright"]
}
}
Commands
injectAxe
This will inject the axe-core
runtime into the page under test. You must run this after a call to page.goto()
and before you run the checkA11y
command.
You run this command with injectAxe()
either in your test, or in a beforeEach
, as long as the visit
comes first.
beforeAll(async () => {
browser = await chromium.launch();
page = await browser.newPage();
await page.goto(`http://localhost:3000/login`);
await injectAxe(page);
});
configureAxe
Purpose
To configure the format of the data used by aXe. This can be used to add new rules, which must be registered with the library to execute.
Description
User specifies the format of the JSON structure passed to the callback of axe.run
Link - aXe Docs: axe.configure
it('Has no detectable a11y violations on load (custom configuration)', async () => {
await configureAxe(page, {
branding: {
brand: String,
application: String,
},
reporter: 'option',
checks: [Object],
rules: [Object],
locale: Object,
});
await checkA11y();
});
checkA11y
This will run axe against the document at the point in which it is called. This means you can call this after interacting with your page and uncover accessibility issues introduced as a result of rendering in response to user actions.
Parameters on checkA11y (axe.run)
page (mandatory)
The page
instance of playwright
.
context (optional)
Defines the scope of the analysis - the part of the DOM that you would like to analyze. This will typically be the document or a specific selector such as class name, ID, selector, etc.
options (optional)
Set of options passed into rules or checks, temporarily modifying them. This contrasts with axe.configure, which is more permanent.
The keys consist of those accepted by axe.run
's options argument as well as a custom includedImpacts
key.
The includedImpacts
key is an array of strings that map to impact
levels in violations. Specifying this array will only include violations where the impact matches one of the included values. Possible impact values are "minor", "moderate", "serious", or "critical".
Filtering based on impact in combination with the skipFailures
argument allows you to introduce axe-playwright
into tests for a legacy application without failing in CI before you have an opportunity to address accessibility issues. Ideally, you would steadily move towards stricter testing as you address issues.
e-effects, such as adding custom output to the terminal.
NOTE: This respects the includedImpacts
filter and will only execute with violations that are included.
skipFailures (optional, defaults to false)
Disables assertions based on violations and only logs violations to the console output. If you set skipFailures
as true
, although accessibility check is not passed, your test will not fail. It will simply print the violations in the console, but will not make the test fail.
Examples
Basic usage
import { chromium, Browser, Page } from 'playwright';
import { injectAxe, checkA11y } from 'axe-playwright';
let browser: Browser;
let page: Page;
describe('Playwright web page accessibility test', () => {
beforeAll(async () => {
browser = await chromium.launch();
page = await browser.newPage();
await page.goto(`file://${process.cwd()}/test/site.html`);
await injectAxe(page);
});
it('simple accessibility run', async () => {
await checkA11y(page);
});
it('check a11y for the whole page and axe run options', async () => {
await checkA11y(page, null, {
axeOptions: {
runOnly: {
type: 'tag',
values: ['wcag2a'],
},
},
});
});
it('check a11y for the specific element', async () => {
await checkA11y(page, 'input[name="password"]', {
axeOptions: {
runOnly: {
type: 'tag',
values: ['wcag2a'],
},
},
});
});
afterAll(async () => {
await browser.close();
});
});
This custom logging behavior results in terminal output like this:
Token of Thanks
The idea is highly inspired by Andy Van Slaars cypress-axe
project.
Before you Go
If it works for you , give a Star! :star:
Consider supporting if it helps you.
- Copyright © 2020- Abhinaba Ghosh