Playwright and axe-core
@axe-core/playwright is Deque's official package for running the axe-core accessibility engine from a Playwright test. Add it to your existing Playwright Test suite and point the suite at TestingBot to scan the pages your tests reach on our cloud browsers.
The scan runs from your test code: the package injects axe-core into the page and returns the results to your test. It uses the axe-core version installed in your project, not the version the TestingBot scheduled scans use, so results can differ slightly between the two.
Installation
npm i -D @playwright/test @axe-core/playwright
Connect to TestingBot
Set connectOptions in playwright.config.js so every test opens its browser on TestingBot.
The Playwright Test guide explains the options and how to run against several browsers.
import { defineConfig } from '@playwright/test'
const capabilities = {
browserName: 'chrome',
browserVersion: 'latest',
'tb:options': {
key: process.env.TB_KEY,
secret: process.env.TB_SECRET
}
}
export default defineConfig({
testDir: './tests',
projects: [
{
name: 'chrome',
use: {
browserName: 'chromium',
connectOptions: {
wsEndpoint: `wss://cloud.testingbot.com/playwright?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
}
}
}
]
})
Example test
This test opens a page, runs axe-core with the WCAG 2.0 and 2.1 level A and AA rules, and fails when there are violations.
import { test, expect } from '@playwright/test'
import AxeBuilder from '@axe-core/playwright'
test('home page has no automated WCAG A/AA violations', async ({ page }) => {
await page.goto('https://example.com/')
const results = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
.analyze()
expect(results.violations).toEqual([])
})
Run it with npx playwright test.
When the test fails, the diff lists each violated rule with the elements that failed it.
A passing test means axe-core found no violations of the rules it ran on that page state. It does not mean the page is accessible: see what automated checks don't catch.
Choosing rules
-
withTags([...])runs only rules with these tags, for examplewcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aaorbest-practice. -
disableRules(['color-contrast'])skips rules you check another way. - Without
withTags, axe-core runs its default rule set. In axe-core 4.11 the WCAG 2.2 ruletarget-sizeis off by default; add thewcag22aatag to run it.
Scanning part of a page
Use include() and exclude() with CSS selectors, for example to leave out a third-party widget you cannot fix:
const results = await new AxeBuilder({ page })
.include('main')
.exclude('#chat-widget')
.analyze()
To check a dialog or menu, open it in your test first and then run the scan: axe-core only checks what is in the page at that moment.
Saving the report
Attach the full result to the Playwright HTML report so you can inspect it after a CI run:
await test.info().attach('accessibility-scan-results', {
body: JSON.stringify(results, null, 2),
contentType: 'application/json'
})