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

Violation levels and their impact

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.

Website Accessibility: WCAG, Screen Readers, Keyboard Navigation

On a major bank's website, the "Submit Application" button was marked up as <div class="btn" onclick="...">. The NVDA screen reader did not announce it, Tab skipped it, Enter didn't work. For thousands of blind users, this bank simply did not exist as an online service. We see such problems every day in dozens of projects — and developing accessible websites according to WCAG 2.2 AA has become the only way to avoid discrimination and legal risks. Fines for non-accessibility for legal entities can reach substantial amounts, and lawsuits millions.

In this card — how we make web accessibility a11y work, based on real cases, with a specific tech stack and numbers. No generic phrases.

Why is Semantic Markup the Foundation of Web Accessibility (a11y)?

Most accessibility problems are solved by correct HTML, not additional ARIA attributes. <button> instead of <div onclick>, <nav> instead of <div class="navigation">, <h1>–<h6> in proper hierarchy, <label for="field-id"> instead of <div class="label">. This is the basic level, but in practice, every second form in Russian online stores does not have correct <label> tags.

ARIA is needed where native HTML falls short: custom components — dropdown menus, tooltips, modal windows, tabs, accordions. And here the complexity begins.

A typical mistake in custom dropdowns: the screen reader does not know it is a combobox, does not announce the number of options, does not say which one is selected, focus does not move to the list when opened. Proper implementation:

• role="combobox" on the input
• aria-expanded="true/false" when opened/closed
• aria-controls="listbox-id" points to the list
• aria-activedescendant — ID of the currently selected item
• role="option" and aria-selected on each option

This is not theory; it is tested with a screen reader. NVDA + Chrome or VoiceOver + Safari is a mandatory part of QA.

<div role="combobox" aria-expanded="false" aria-controls="listbox-1" aria-activedescendant="" tabindex="0">
  <label for="input-1">Select city</label>
  <input id="input-1" type="text" role="combobox" aria-autocomplete="list" />
  <ul id="listbox-1" role="listbox" aria-label="Cities">
    <li role="option" aria-selected="false" id="opt-1">Moscow</li>
    <li role="option" aria-selected="false" id="opt-2">St. Petersburg</li>
  </ul>
</div>

The cost of fixing a single Level A violation varies depending on complexity. Implementing a11y from the design stage reduces the refactoring budget by 2–3 times compared to retrofitting a finished site.

How to Properly Build Keyboard Navigation?

Tab order should match the visual order of elements. If in HTML the "Cancel" button comes before "Confirm", but CSS swaps them — the keyboard user is confused.

Focus trap in modal windows. When a modal opens, Tab should cycle only within it. When closing, return focus to the element that opened the modal. Without this, the user ends up at the top of the page after closing.

tabindex="-1" — element does not enter Tab sequence but can receive focus programmatically. Used for elements that receive focus via JavaScript (section headings after anchor navigation).

tabindex="1" and above is almost always an error. Explicit order breaks natural order and creates unpredictable behavior. Control order via DOM, not tabindex.

Skip links — a "Skip to content" link, hidden visually, visible on Tab. Allows screen reader users to skip repetitive navigation.

Color and Contrast: Requirements and Common Violations

WCAG 2.2 AA requires contrast 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold). AAA requires 7:1 and 4.5:1.

The most common violations: gray placeholder in inputs (#999 on white = 2.9:1), light gray secondary text, white text on pastel backgrounds.

Color should not be the sole indicator: "required fields are red" without an asterisk — violation for color blind users.

Testing tools: axe DevTools, WAVE, Accessibility Inspector in Chrome DevTools. axe-core integrates into Playwright tests: automatic check of 80+ rules on every deployment. Manual testing finds about 60% more errors than automated.

What Is Important About Media Content and Dynamics?

Images without alt — a common basic failure. alt should be meaningful: not alt="image_123.jpg", but a description of content relevant to context. Decorative images — alt="" (empty, not missing attribute).

Video should have captions. YouTube auto-captions are not a standard; they make mistakes. WebVTT files with correct captions for all educational and marketing video content.

Animations — a problem for users with vestibular disorders. @media (prefers-reduced-motion: reduce) — media query that disables or slows animations for users with that OS setting.

What Changed in WCAG 2.2?

Version 2.2 came into effect with new criteria:

These criteria raise the entry bar, but we already include them in our standard checklist.

Audit and Remediation

Automated tools find about 30–40% of violations. The rest is only manual testing. Minimum scenario: go through the entire critical user flow (registration, purchase, form) using only keyboard and screen reader.

Process

1. Automated audit — axe-core, Lighthouse, WAVE — outputs 80+ rules.
2. Manual testing — NVDA, VoiceOver, keyboard — 2–3 days for a typical site.
3. Violation prioritization — P1 (blocks usage), P2 (creates difficulties), P3 (enhancements).
4. Fixing — iteratively, integrate checks into CI via Playwright + axe.
5. Re-audit — close all P1/P2 before release.
6. Documentation and handover — report with results, maintenance recommendations, team training.

Results and Scope

• Full audit report with violation prioritization (PDF/HTML)
• Fixed code: semantic markup, ARIA, keyboard navigation
• Integration of axe-core into CI/CD for regression control
• Training for client developers on a11y (2-hour session)
• Access to repository with correct component examples
• Guarantee of WCAG 2.2 AA compliance at time of delivery

Timeline

Budget is calculated individually after the audit. Contact us — we will evaluate your project in 1 day. Get a consultation and free checklist when ordering an audit.

Experience and Guarantees

We have been working in web accessibility a11y for over 8 years. Completed more than 50 projects for banks, retail, and government. Certified specialists (IAAP CPACC, WAS). We guarantee passing a third-party audit or will fix for free.

WCAG 2.2 Standard — official W3C recommendation defining web content accessibility requirements.

Wikipedia: Web Content Accessibility Guidelines
Wikipedia: ARIA

— web accessibility levels a11y per version 2.2.

Order an audit now — get a checklist and preliminary estimate for free. Contact us – we will respond within an hour.