DEV Community: Vadym Liubyvyi

Accessibility testing with Playwright and axe-core

Vadym Liubyvyi — Fri, 23 Oct 2026 08:22:52 +0000

Playwright drives a real browser, and axe-core is the open-source rule engine behind most automated accessibility checkers. Together they turn WCAG checks into ordinary tests: a page that gains a button without a name or a text with low contrast breaks the build before it reaches customers. This guide shows working examples with @axe-core/playwright, the options for React components and Storybook, CI tips, and the limits you should know about.

The examples follow the official Playwright accessibility testing guide and the @axe-core/playwright README. We use the same engine in our own scanner.

Install

npm install --save-dev @playwright/test @axe-core/playwright

The package version follows the axe-core version it ships. Its README notes that it does not follow semantic versioning, so pin the version and update it on purpose: a new axe release can add rules that find new problems.

A first WCAG test

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

const WCAG_AA = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'];

test('home page has no detectable WCAG A/AA violations', async ({ page }) => {
    await page.goto('/');

    const results = await new AxeBuilder({ page }).withTags(WCAG_AA).analyze();

    expect(results.violations).toEqual([]);
});

withTags limits the run to the rules tagged with these WCAG versions and levels. Without it, axe also runs its best-practice rules, which are useful but are not WCAG requirements.

Test the states people actually see

A page is more than its first render. Open the menu, the cart drawer or the cookie dialog first, then scan just that part with include:

test('mobile menu is accessible when open', async ({ page }) => {
    await page.goto('/');
    await page.getByRole('button', { name: 'Menu' }).click();

    const results = await new AxeBuilder({ page })
        .include('#navigation-menu')
        .withTags(WCAG_AA)
        .analyze();

    expect(results.violations).toEqual([]);
});

Good candidates on a shop: product page with options selected, cart with items, checkout with validation errors shown, the account login form. Using getByRole in your tests is a small accessibility test on its own: if Playwright cannot find the button by its role and name, a screen reader user probably cannot either.

Known issues without switching tests off

Real projects have problems you cannot fix today, for example inside a third-party widget. The README offers three tools:

const results = await new AxeBuilder({ page })
    .exclude('#third-party-chat')      // skip an element
    .disableRules(['color-contrast'])  // skip a rule (use rarely)
    .withTags(WCAG_AA)
    .analyze();

A better pattern from the Playwright guide is a snapshot of fingerprints: you record which rules fail on which elements, and the test fails only when something new appears.

const fingerprints = (results) =>
    results.violations.map((v) => ({
        rule: v.id,
        targets: v.nodes.map((n) => n.target),
    }));

expect(fingerprints(results)).toMatchSnapshot();

Two notes from the README: include and exclude take one selector per call (chain them for several), and calling withTags, withRules, disableRules or options again overrides the earlier call.

Fail on what matters first

If the backlog is large, start with the most severe problems. Every violation carries an impact of minor, moderate, serious or critical:

const blocking = results.violations.filter((v) =>
    ['serious', 'critical'].includes(v.impact),
);
expect(blocking).toEqual([]);

Attach the full result to the report so whoever fixes it sees every element:

// inside test('…', async ({ page }, testInfo) => { … })
await testInfo.attach('accessibility-scan-results', {
    body: JSON.stringify(results, null, 2),
    contentType: 'application/json',
});

The Playwright guide also shows how to wrap AxeBuilder in a test fixture, so every test gets the same tags and exclusions from one place.

React components: jest-axe and vitest-axe

For component tests that render into JSDOM, jest-axe and vitest-axe add a toHaveNoViolations matcher:

import { render } from '@testing-library/react';
import { axe } from 'vitest-axe';
import 'vitest-axe/extend-expect';

it('renders an accessible form', async () => {
    const { container } = render(<SignupForm />);
    expect(await axe(container)).toHaveNoViolations();
});

They are fast and catch missing labels and names early. Two limits from their READMEs: jest-axe turns off colour contrast checks because they do not work in JSDOM, and vitest-axe does not work with the happy-dom environment. Contrast, layout, zoom and focus need a real browser, so keep the Playwright tests for full pages.

Storybook

The Storybook accessibility addon runs axe-core on every story:

npx storybook add @storybook/addon-a11y

Set parameters.a11y.test to 'error' for stories that must stay clean: violations then fail the test in the Storybook UI and in CI. 'todo' shows them as warnings only, and 'off' skips the automatic check.

CI tips

Run in the same pipeline as your other tests. The Playwright CI guide uses npm ci, npx playwright install --with-deps and npx playwright test, and uploads the playwright-report/ folder as an artifact.
Test a built, production-like page, not a dev server with debugging overlays.
Pick a short list of key URLs — home, a category, a product, cart, checkout, login, a content page — instead of crawling everything on every commit.
Keep the axe version pinned and update it in its own pull request.
Do not hide failures with disableRules for long; prefer exclude for one element or the snapshot pattern.

What automated tests cannot tell you

The axe-core README says that you can find on average 57% of WCAG issues automatically, and the Playwright guide is equally clear that automated testing cannot detect all types of WCAG violations. An empty violations array does not mean a page meets WCAG 2.2 AA. You still need a keyboard walk-through, a zoom and reflow check and a screen reader test. Our WCAG testing guide describes that part, and the WCAG 2.2 checklist marks which points need a person.

Where Pandus fits

Tests in CI protect the code you change. They do not see what happens on the live site afterwards: a theme update, a new app or plugin, a marketing banner, a product description pasted from a supplier. Pandus checks the production site: every page each week, with the same axe-core engine in a real browser, and a report a shop owner can read.

The API starts checks and returns results as JSON, with webhooks when a check finishes or new issues appear — useful after a deployment.
The browser extension checks a page as your browser shows it, including staging and pages behind a login.
The free WCAG checker checks one public page without an account.

Pandus is an automated check, not a full audit, and not legal advice. A comparison of other tools is in accessibility testing tools.

Frequently asked questions

How do I test accessibility with Playwright?

Install @axe-core/playwright, open the page in a Playwright test, run new AxeBuilder({ page }).analyze() and assert that the violations array is empty. Limit the run to WCAG rules with withTags, for example wcag2a, wcag2aa, wcag21a, wcag21aa and wcag22aa.

Does a passing axe test mean the page meets WCAG?

No. Automated rules find a part of WCAG problems only. Deque, the maker of axe-core, puts it at about 57% of issues on average. Keyboard flow, meaningful alternative text, focus order and understandable errors still need a person.

Can I use jest-axe or vitest-axe instead?

Yes, for components rendered in JSDOM. They are fast, but jest-axe turns off colour contrast checks because they do not work in JSDOM. Use Playwright for full pages in a real browser, where contrast, layout and focus can be checked.

How do I test Storybook components for accessibility?

Add @storybook/addon-a11y. It runs axe-core on every story; with parameters.a11y.test set to error, violations fail the test in the Storybook UI and in CI.

Should the build fail on every violation?

Start by failing on serious and critical issues and keep a snapshot of known ones, so new problems break the build while old ones are fixed step by step. Tighten the rule once the backlog is gone.

Sources

Playwright, Accessibility testing: https://playwright.dev/docs/accessibility-testing
Playwright, Setting up CI: https://playwright.dev/docs/ci-intro
Deque, @axe-core/playwright README: https://github.com/dequelabs/axe-core-npm/blob/develop/packages/playwright/README.md
Deque, axe-core README: https://github.com/dequelabs/axe-core
jest-axe README: https://github.com/NickColley/jest-axe
vitest-axe README: https://github.com/chaance/vitest-axe
Storybook, Accessibility tests: https://storybook.js.org/docs/writing-tests/accessibility-testing

Originally published on pandus.online. Pandus is an automated accessibility check, not a full audit, and not legal advice.

APCA vs WCAG contrast: which one should you use?

Vadym Liubyvyi — Fri, 23 Oct 2026 08:22:47 +0000

Designers who check colours sooner or later meet two numbers: the WCAG contrast ratio (4.5:1, 3:1) and an APCA value such as Lc 75. They do not always agree. This page explains how the WCAG 2 formula works, what APCA is and what its status really is, and how Windows high contrast mode relates to both.

The short answer for anyone who has to meet a requirement: laws and standards use the WCAG 2 contrast ratio. This is general information, not legal advice.

The WCAG 2 formula, step by step

WCAG 2.2 defines contrast in two steps, both in its glossary.

1. Relative luminance — how bright a colour is, from 0 for the darkest black to 1 for the lightest white. For each sRGB channel:

C_srgb = C_8bit / 255
C = C_srgb / 12.92                         if C_srgb <= 0.04045
C = ((C_srgb + 0.055) / 1.055) ^ 2.4       otherwise

L = 0.2126 * R + 0.7152 * G + 0.0722 * B

The weights show that the eye is far more sensitive to green than to blue. (Before May 2021 the WCAG text used 0.03928 as the threshold; the W3C notes this has no practical effect.)

2. Contrast ratio — with L1 the luminance of the lighter colour and L2 of the darker one:

contrast ratio = (L1 + 0.05) / (L2 + 0.05)

The result goes from 1:1 (the same colour) to 21:1 (black on white). An example: grey #767676 has a luminance of about 0.181, so on white it reaches (1 + 0.05) / (0.181 + 0.05) ≈ 4.54:1 and passes the 4.5:1 minimum. One step lighter, #777777, gives about 4.48:1 and fails — W3C says the values must not be rounded, so 4.499:1 does not meet 4.5:1.

The thresholds

Criterion	Level	Required ratio
1.4.3 Contrast (Minimum)	AA	4.5:1 text, 3:1 large text
1.4.11 Non-text Contrast	AA	3:1 for icons, field borders, focus indicators and other UI parts
1.4.6 Contrast (Enhanced)	AAA	7:1 text, 4.5:1 large text

Large text is at least 18 point (24 CSS pixels) or 14 point bold (about 18.66 CSS pixels). The W3C explains the 4.5:1 value as compensating for the loss of contrast sensitivity that comes with about 20/40 vision. Check any pair with our contrast checker.

Known limits of the WCAG 2 formula

The formula is simple and testable, which is why it works for regulation. It also has limits that W3C's own Understanding document mentions: it does not look at font weight, and thin or unusual fonts can look much fainter than their nominal colour because of anti-aliasing — "a contrast ratio that nominally passes … but has a much lower contrast in practice". The recommendation there is to use heavier fonts or a colour pair that exceeds the minimum. The formula also assumes sRGB colours.

The formula is also symmetric: swapping text and background gives the same ratio. The APCA project goes further and states that WCAG 2 contrast math "does not accurately model human visual perception nor visual impairments" — the starting point for APCA.

What APCA is

The Accessible Perceptual Contrast Algorithm is described in its official repository as an assessment method for predicting the perceived contrast between sRGB colours on a monitor, developed for the W3 "Silver" / WCAG 3 work. The differences from WCAG 2 in practice:

Order matters. The first colour is the text, the second the background; the result is signed, and the sign shows the polarity (dark on light or light on dark).
A different scale. The output is an Lc value, roughly from −108 to 106, not a ratio.
Size and weight are part of the answer. A lookup function returns, for an Lc value, the font sizes needed at weights 100 to 900. The README gives rules such as a maximum of Lc 90 for fonts larger than 24 px at weight 300 or more.
Beta. The library (apca-w3 on npm) is in public beta validation, and the README calls the related draft criterion a work in progress.

Is APCA part of WCAG 3?

Not as a final decision. Two facts, both checked on the official sources:

The APCA repository says APCA is being evaluated as a replacement for the WCAG 2 contrast math for future standards.
The current WCAG 3 Working Draft, dated 10 September 2026, says: "The contrast algorithm used in WCAG 3 is yet to be determined." Its text contrast requirements have the status developing, with the measure left open. The draft also says it is inappropriate to cite it as other than a work in progress.

So APCA is a candidate, WCAG 3 is a draft, and neither is normative. WCAG 2.2 is the current W3C Recommendation, and EN 301 549, the European standard behind the European Accessibility Act, refers to WCAG 2 success criteria. A colour pair that passes APCA but fails 4.5:1 still fails the requirement.

WCAG or APCA: a practical rule

Meet the WCAG 2 ratio for every text and every UI component. That is the requirement.
Use APCA, if you like, as a design aid on top: for example to choose a heavier weight for thin text, or to notice that a pair that just passes 4.5:1 is still hard to read in light text on a dark background.
Do not claim APCA results as conformance. Reports, statements and tenders refer to WCAG 2.

Windows high contrast mode and forced colours

"WCAG high contrast mode" is a common search, but it mixes two things.

What it is. Windows offers contrast themes (Windows 11; called high contrast mode in Windows 10). Microsoft documents them under Settings → Accessibility → Contrast themes, with the shortcut Left Alt + Left Shift + Print Screen. Browsers then apply the user's limited palette to web pages. CSS detects this with the forced-colors media feature: active means the user agent enforces a user-chosen limited colour palette, and only system colours are available to the author.

What WCAG says. No WCAG 2.2 success criterion requires a high contrast mode or support for forced colours by name, and a site does not need to offer its own high contrast switch to meet AA. But your code can break the page for people who use such a mode, and then other criteria fail:

Focus. W3C technique C40 warns that user agents commonly suppress box-shadow in forced-color modes, so a focus indicator made only with a shadow disappears. C40 suggests combining it with outline: 2px transparent solid for compatibility with forced-color modes — relevant for 2.4.7 Focus Visible.
Icons and borders. Icons drawn with background images, and controls distinguished only by a background colour, can vanish. This touches 1.4.11 Non-text Contrast and 1.4.1 Use of Color.
Do not assume more contrast. The Media Queries specification notes that forced colours do not necessarily mean a preference for more contrast; for that, prefers-contrast exists.

Testing a few key pages with a contrast theme switched on is good practice, even though no criterion names it.

What our checks do

Our checks use the WCAG 2 contrast ratio, as the requirements do: low text contrast at AA (1.4.3), and enhanced contrast at AAA (1.4.6), which our reports show apart from the AA results. We do not report APCA values. Run the free WCAG checker on a page, or test one pair with the contrast checker. Our checks are an automated check, not a full audit, and not legal advice.

Frequently asked questions

Should I use WCAG or APCA for contrast?

Use the WCAG 2 contrast ratio to meet requirements: it is what WCAG 2.2, EN 301 549 and the laws built on them refer to. APCA can be a useful second opinion in design, but it is not part of any normative standard today.

Is APCA part of WCAG 3?

Not as a decision. APCA was developed as a candidate method for WCAG 3 and is in public beta. The current WCAG 3 Working Draft of September 2026 says the contrast algorithm is yet to be determined, and WCAG 3 itself is a draft, not a standard.

How is the WCAG contrast ratio calculated?

Convert both colours to relative luminance: linearise each sRGB channel, then L = 0.2126 R + 0.7152 G + 0.0722 B. The ratio is (L1 + 0.05) / (L2 + 0.05), with L1 the lighter colour. It ranges from 1:1 to 21:1 and is not rounded.

Does WCAG require support for Windows high contrast mode?

No WCAG criterion names high contrast or forced colours mode. But your own CSS can break the page in that mode, for example a focus ring made only with box-shadow, which browsers commonly remove there. Testing in a forced colours mode is good practice.

Can a colour pair pass WCAG and still be hard to read?

Yes. The WCAG formula does not account for font weight, and thin fonts with anti-aliasing can look fainter than their colour suggests. The W3C recommends heavier fonts or more contrast than the minimum in that case.

Sources

W3C, WCAG 2.2 (definitions of relative luminance and contrast ratio): https://www.w3.org/TR/WCAG22/
W3C, Understanding 1.4.3 Contrast (Minimum): https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
W3C, WCAG 3.0 Working Draft: https://www.w3.org/TR/wcag-3.0/
APCA, apca-w3 repository: https://github.com/Myndex/apca-w3
W3C, Technique C40, two-colour focus indicator: https://www.w3.org/WAI/WCAG22/Techniques/css/C40
W3C, Media Queries Level 5 (forced-colors): https://www.w3.org/TR/mediaqueries-5/
Microsoft, Change color contrast in Windows: https://support.microsoft.com/en-us/windows/change-color-contrast-in-windows-fedc744c-90ac-69df-aed5-c8a90125e696

Originally published on pandus.online. Pandus is an automated accessibility check, not a full audit, and not legal advice.