Axe-core: Automating WCAG 2.1 Testing with Jest and Playwright
Often accessibility (a11y) issues are only detected during manual testing or, worse, in production. Each missed critical bug – for example, missing alt on an image or non-functional keyboard navigation – can cost you reputation and hefty fines. We automate WCAG 2.1/2.2 checks with axe-core to catch such problems at the CI/CD stage. The Deque Systems library automatically detects about 57% of violations, leaving the rest for manual audit. Experience shows that after implementing axe-core, a11y regressions drop by 70–80%.
How axe-core helps automate accessibility testing
axe-core works both in the browser and in Node.js, and can be easily embedded into existing test frameworks. Its rules are based on WCAG 2.1, grouped by tags (wcag2a, wcag2aa, wcag21aa). For each page element, the library checks: contrast, heading semantics, form accessibility, ARIA attributes, and much more. The result is a structured report with the type, severity level, and a reference to the element.
Integration with Jest + Testing Library
npm install --save-dev jest-axe @testing-library/react // __tests__/accessibility.test.tsx import { render } from '@testing-library/react'; import { axe, toHaveNoViolations } from 'jest-axe'; expect.extend(toHaveNoViolations); describe('Component accessibility', () => { it('Button has no violations', async () => { const { container } = render(<Button>Submit</Button>); const results = await axe(container); expect(results).toHaveNoViolations(); }); it('Form has no violations', async () => { const { container } = render( <form> <label htmlFor="email">Email</label> <input id="email" type="email" /> <button type="submit">Sign in</button> </form> ); const results = await axe(container, { rules: { 'color-contrast': { enabled: true }, 'label': { enabled: true }, }, }); expect(results).toHaveNoViolations(); }); }); Integration with Playwright
// tests/accessibility.spec.ts import { test, expect } from '@playwright/test'; import AxeBuilder from '@axe-core/playwright'; test('Homepage passes WCAG 2.1 AA', async ({ page }) => { await page.goto('/'); const results = await new AxeBuilder({ page }) .withTags(['wcag2a', 'wcag2aa', 'wcag21aa']) .exclude('.cookie-banner') // Exclude third-party components .analyze(); expect(results.violations).toEqual([]); }); test('Registration form – accessibility', async ({ page }) => { await page.goto('/register'); const results = await new AxeBuilder({ page }) .include('#registration-form') .analyze(); // Detailed report on failure if (results.violations.length > 0) { console.table(results.violations.map(v => ({ id: v.id, impact: v.impact, description: v.description, nodes: v.nodes.length, }))); } expect(results.violations).toEqual([]); }); Why integrate axe-core into CI/CD?
Manual accessibility testing is hard to scale: a single page audit takes 2–3 hours. Integrating axe-core into CI/CD (e.g., via a Playwright test before each deployment) automates this check. We guarantee that critical violations won't reach production. In one project with 500+ pages, after configuring axe-core, a11y regressions dropped from 30 to 2–3 per month.
Comparison of manual and automated audit
| Characteristic | Manual audit | axe-core |
|---|---|---|
| Time per page | 15–30 minutes | 5–10 seconds |
| Coverage of critical violations | 100% (with a qualified specialist) | ~90% |
| Launch frequency | Once per sprint | Every commit |
| Accuracy | Depends on fatigue | Stable |
Violation levels and their impact
| Impact | Meaning | Example | WCAG certification |
|---|---|---|---|
| critical | Blocks access | Image without alt | Does not pass any level |
| serious | Significantly hinders | Form without label | Does not pass AA |
| moderate | Makes usage difficult | Insufficient contrast | May pass A but not AA |
| minor | Small inconvenience | Wrong lang | Passes, but better to fix |
Where to start: typical mistakes when setting up axe-core
On first run, axe-core often produces false positives on third-party iframes, cookie banners, or dynamically loaded content. To avoid noise, configure exceptions via exclude() and specify precise check tags (e.g., wcag2aa). Also, it's important to properly configure rules: disable those that don't apply to the project (e.g., color-contrast for components with custom colors).
Checklist for implementing axe-core
- Exclude iframes and third-party widgets.
- Set up custom rules for specific components.
- Integrate with Jest for unit component tests.
- Integrate with Playwright for e2e tests of critical pages.
- Add run to CI/CD (GitHub Actions, GitLab CI).
- Set up failure notifications.
What's included in the work
- Documentation: report of current violations, list of rules, exceptions for third-party components.
- Integration: setting up axe-core in Jest (unit component tests), Playwright (e2e page tests), and Storybook (visual inspection) – as needed.
- CI/CD pipeline: adding accessibility tests to GitLab CI, GitHub Actions, or similar.
- Team training: basic lecture (1–2 hours) on WCAG and working with axe-core.
- Support: consultations on fixing identified violations for a month after implementation.
Timelines
Configuring axe-core in Jest + Playwright, covering key pages and components: 2–3 business days. If the project uses non-standard frameworks (Angular, Vue 3 with SSR) or requires deep customization of rules, the timeline may increase to 5 days. We work with a 50% prepayment; the final cost is calculated individually after auditing your code.
Our team has 5+ years of experience in a11y auditing and over 50 successful projects. Contact us for a consultation on integrating axe-core into your project. Order an accessibility audit – it will reduce risks and save time.