Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
injectAxe
✓ import { injectAxe } from 'axe-playwright';
✗ const injectAxe = require('axe-playwright').injectAxe;
Used to inject the axe-core runtime into the Playwright page.
configureAxe
✓ import { configureAxe } from 'axe-playwright';
✗ const configureAxe = require('axe-playwright').configureAxe;
Used to globally configure axe-core's behavior, rules, or localization.
checkA11y
✓ import { checkA11y } from 'axe-playwright';
✗ const checkA11y = require('axe-playwright').checkA11y;
The primary function to execute accessibility checks on the current page context.
This quickstart demonstrates how to set up `axe-playwright` in a Playwright test, inject `axe-core`, run basic accessibility checks, and apply custom configurations for `axe-core`.
import { test, expect } from '@playwright/test';
import { injectAxe, checkA11y, configureAxe } from 'axe-playwright';
test.describe('Accessibility testing with axe-playwright', () => {
test.beforeEach(async ({ page }) => {
// For a real application, you'd navigate to your app's URL
// For this example, we'll create a simple page content
await page.setContent(`
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Accessibility Test Page</title>
</head>
<body>
<h1>Welcome</h1>
<button onclick="alert('Hello')">Click Me</button>
<img src="nonexistent.png" alt=""> <!-- Missing alt text for demonstration -->
<a href="#">Link without text</a>
</body>
</html>
`);
// Inject axe-core runtime after page content is loaded
await injectAxe(page);
});
test('should not have any detectable accessibility violations on load', async ({ page }) => {
// Basic check with default axe-core configuration
// This will typically report 'image-alt' and 'link-name' violations from the example content
await checkA11y(page, null, {
detailedReport: true,
detailedReportOptions: { html: true }
});
});
test('should allow custom axe-core configuration to filter results', async ({ page }) => {
// Configure axe-core to ignore specific rules for this test
await configureAxe(page, {
rules: {
'image-alt': { enabled: false }, // Disable 'image-alt' rule
}
});
// Now checkA11y should only report 'link-name' violation (if not further configured)
await checkA11y(page, null, {
includedImpacts: ['critical', 'serious', 'moderate'] // Only report high impact issues
});
});
});
// To run this example:
// 1. Ensure you have Playwright and axe-playwright installed: `npm i -D playwright @playwright/test axe-playwright`
// 2. Install Playwright browsers: `npx playwright install`
// 3. Save the code as a TypeScript file (e.g., `a11y.spec.ts`)
// 4. Run tests with Playwright: `npx playwright test a11y.spec.ts`
Errors
Common errors & fixes
ReferenceError: injectAxe is not defined
The `injectAxe` function (or `configureAxe`/`checkA11y`) was called without being imported.
fixAdd the necessary import statement: `import { injectAxe } from 'axe-playwright';` (and other functions as needed) to your test file. TypeError: page.checkA11y is not a function
`axe-playwright` functions are standalone and operate on the Playwright `page` object as an argument, rather than extending the `page` object with custom commands.
fixUse `checkA11y(page, ...)` instead of attempting to call `page.checkA11y(...)`.
Cannot find name 'checkA11y'. Did you mean 'consoleA11y'?
TypeScript configuration is missing type definitions for `axe-playwright`, preventing the compiler from recognizing the library's functions.
fixEnsure `"types": ["axe-playwright"]` is included in the `compilerOptions` of your `tsconfig.json`.
Playwright installation not found.
The required `playwright` peer dependency is not installed in the project.
fixRun `npm install playwright` or `yarn add playwright --dev` to install Playwright.
Audit
Dependencies
playwrightrequiredRequired peer dependency for Playwright browser automation.