Skip to main content

Frontend development · Intermediate · 26 min

Test a page for accessibility with axe and a screen reader

By Padding · Updated 18 Nov 2026
Node.js 26 · Playwright 1.65 · axe-core 4.14 · WCAG 2.2 · checked in Chromium 159

You will have a Playwright test that runs axe on the Larkfield Clinic booking page and fails on any new violation, a keyboard test that catches what axe cannot see, and a written checklist for a short screen reader pass.

On this page

An automated accessibility checker reads the page's code and the browser's computed styles and reports rules that are broken: an image with no text alternative, a field with no label, grey text that is too pale. It is fast and it never gets bored, so it belongs in your tests. It cannot tell you whether a person can actually use the page. It does not press Tab, it does not notice that a "button" is a div nobody can reach, and it cannot hear that a screen reader reads your form in a confusing order.

So this tutorial pairs the two. You run axe-core, the open-source rules engine from Deque, through Playwright against one page, fix what it finds, and keep it as a test that fails when someone adds a new violation. Then you do the checks automation cannot: a keyboard pass, turned into a second test, and a short screen reader pass that follows a written script.

The page is the Your details screen of the Larkfield Clinic booking app, the fictional community clinic used across the design track. The patient has picked a Nurse appointment on Tuesday 9 December at 10:30 and now gives their full name, date of birth, mobile number and an optional email, with a checkbox for a text reminder. The colours come from the Larkfield high-fidelity design: accent #0F5E5A, text #1B1F24, text-muted #5A6270, border #7D8592 and the canvas #F6F7F8 background. The first version you write has seven problems planted in it. Five are the kind a rules engine finds, and two are not.

Step 1 · Write the page with its problems

Make a demo folder with the page, its stylesheet and a small logo:

Bash
mkdir -p ~/a11y-check-demo
cd ~/a11y-check-demo
cat > index.html <<'HTML'
<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Your details · Larkfield Clinic</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header class="top">
    <button id="back" class="icon-button" type="button" onclick="history.back()">
      <svg width="24" height="24" viewBox="0 0 24 24"><path d="M15 5l-7 7 7 7" fill="none" stroke="currentColor" stroke-width="2"/></svg>
    </button>
    <img src="logo.svg" width="120" height="32">
  </header>
  <main>
    <h1>Your details</h1>
    <p class="service">Nurse appointment · Tue 9 Dec, 10:30</p>
    <form id="details" action="confirm.html" method="get">
      <label for="full-name">Full name</label>
      <input id="full-name" name="name" autocomplete="name">

      <label for="dob">Date of birth</label>
      <p class="hint">For example, 31 03 1985</p>
      <input id="dob" name="dob" inputmode="numeric" autocomplete="bday">

      <span class="label">Mobile number</span>
      <input id="mobile" name="mobile" type="tel" autocomplete="tel">

      <label for="email">Email (optional)</label>
      <input id="email" name="email" type="email" autocomplete="email">

      <label class="check"><input id="reminder" name="reminder" type="checkbox"> Text me a reminder the day before</label>

      <div id="continue" class="button" onclick="document.getElementById('details').submit()">Continue</div>
    </form>
  </main>
</body>
</html>
HTML
cat > style.css <<'CSS'
* { box-sizing: border-box; }
body { margin: 0; font-family: system-ui, sans-serif; line-height: 1.5; color: #1B1F24; background: #F6F7F8; }
.top { display: flex; align-items: center; gap: 0.75rem; padding: 0.5rem 1rem; background: #FFFFFF; border-bottom: 1px solid #D5D9DF; }
.icon-button { display: grid; place-items: center; width: 44px; height: 44px; border: 0; background: none; color: #1B1F24; }
main { max-width: 30rem; margin: 0 auto; padding: 1rem; }
.service { color: #5A6270; margin-top: 0; }
label, .label { display: block; font-weight: 600; margin-top: 1rem; }
.hint { color: #9AA0A8; margin: 0; }
input { display: block; width: 100%; font: inherit; padding: 0.6rem; border: 1px solid #7D8592; border-radius: 0.5rem; background: #FFFFFF; }
input:focus { outline: none; }
.check { display: flex; align-items: center; gap: 0.5rem; font-weight: 400; margin: 1.25rem 0; }
.check input { width: 24px; height: 24px; flex: none; }
.button { display: block; width: 100%; padding: 0.8rem; border: 0; border-radius: 0.5rem; background: #0F5E5A; color: #FFFFFF; font: inherit; font-weight: 600; text-align: center; cursor: pointer; }
CSS
cat > logo.svg <<'SVG'
<svg xmlns="http://www.w3.org/2000/svg" width="120" height="32" viewBox="0 0 120 32"><rect width="32" height="32" rx="8" fill="#0F5E5A"/><text x="40" y="22" font-family="system-ui, sans-serif" font-size="15" fill="#1B1F24">Larkfield</text></svg>
SVG

Do not fix anything yet. Looking at it, you may spot some of the problems: the <html> element has no lang, the logo has no alt, the back button holds only an icon, "Mobile number" is a span rather than a label, and the date hint is a pale grey. Those five are rule breaks that axe can find. The other two are the div pretending to be a button and the outline: none on focused fields, and you will see in a later step that axe says nothing about them.

Check it worked

Open index.html in a browser (open index.html on macOS, xdg-open index.html on Linux, or drag the file into a window). You see a white bar with a back arrow and the Larkfield logo, the heading "Your details", the line "Nurse appointment · Tue 9 Dec, 10:30", four fields with a checkbox, and a teal Continue bar. It looks finished. That is the point: none of the seven problems shows up to a sighted mouse user.

Step 2 · Install Playwright and axe, and write the test

Playwright drives a real browser from Node.js, and @axe-core/playwright injects axe-core into the page it has open and runs the rules there. Install pinned versions into the demo folder, then the Chromium build that this Playwright release expects:

Bash
cd ~/a11y-check-demo
npm init -y > /dev/null
npm install --save-dev @playwright/test@1.65.1 @axe-core/playwright@4.14.0
npx playwright install --with-deps chromium

--with-deps also installs the system libraries Chromium needs on Linux, using sudo, so it may ask for your password. On macOS and Windows it only downloads the browser. The download is a few hundred megabytes, so on prepaid mobile data run it once on a Wi-Fi connection and it stays cached for later projects.

Add a small Playwright config, so the tests live in tests/ and results print as a plain list, and then the test itself:

Bash
cd ~/a11y-check-demo
cat > playwright.config.js <<'JS'
const { defineConfig } = require('@playwright/test');

module.exports = defineConfig({
  testDir: 'tests',
  reporter: 'list',
  use: { browserName: 'chromium' },
});
JS
mkdir -p tests
cat > tests/a11y.spec.js <<'JS'
const { test, expect } = require('@playwright/test');
const AxeBuilder = require('@axe-core/playwright').default;
const { pathToFileURL } = require('node:url');
const path = require('node:path');

const PAGE = pathToFileURL(path.join(__dirname, '..', 'index.html')).href;

test('Your details has no WCAG A or AA violations that axe can detect', async ({ page }) => {
  await page.goto(PAGE);
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
    .analyze();

  for (const v of results.violations) {
    console.log(`${v.id} [${v.impact}] ${v.help}`);
    for (const node of v.nodes) console.log(`  at ${node.target.join(' ')}`);
  }
  for (const item of results.incomplete) {
    console.log(`needs a human: ${item.id} on ${item.nodes.length} element(s)`);
  }

  const ids = results.violations.map((v) => v.id);
  expect(ids, `axe found: ${ids.join(', ')}`).toEqual([]);
});
JS

Three choices in that file matter:

  • withTags limits the run to WCAG rules. axe also ships "best practice" rules that are useful advice but not WCAG failures. Running only the WCAG 2.0, 2.1 and 2.2 level A and AA tags means a red test is a conformance problem you have to fix, not a matter of opinion. Add 'best-practice' to the list later if your team agrees to treat those as failures too.
  • Violations and incomplete results are different. A violation is a rule that definitely failed. An incomplete result is something axe could not decide, for example text over a background image whose colour it cannot read. Those are printed for a person to check, and they do not fail the test.
  • The assertion is on rule ids. Comparing the list to [] means the failure message names every broken rule in one go, rather than stopping at the first.

Check it worked

Run ls ~/a11y-check-demo and you see index.html, logo.svg, node_modules, package-lock.json, package.json, playwright.config.js, style.css and tests. Run npx playwright --version in the folder and it prints Version 1.65.1.

Step 3 · Run axe and read the report

Run the test against the page as it stands:

Bash
cd ~/a11y-check-demo
npx playwright test

It fails, which is what you want from a page with problems. The printed lines look something like this, one per broken rule, with the CSS selector of each element underneath:

Text
button-name [critical] Buttons must have discernible text
  at #back
color-contrast [serious] Elements must meet minimum color contrast ratio thresholds
  at .hint
html-has-lang [serious] <html> element must have a lang attribute
  at html
image-alt [critical] Images must have alternative text
  at img
label [critical] Form elements must have labels
  at #mobile

Read each one as a sentence about a person, not a code to silence:

  • html-has-lang: without lang, a screen reader guesses which voice and pronunciation rules to use. On a phone set to French or Hausa, it may read English words with the wrong ones.
  • image-alt: the logo has no text alternative, so a screen reader may read out the file name, "logo dot svg".
  • button-name: the back button contains only a drawing. A screen reader announces "button" and nothing else.
  • label: the mobile field has text next to it, but nothing ties that text to the field. Tabbing into it, a screen reader says "edit text" with no name.
  • color-contrast: the hint is #9AA0A8 on #F6F7F8, well under the 4.5 to 1 that WCAG 2.2 asks of normal-size text.

Each violation also has a helpUrl property that links to Deque's page for that rule, if you want the full explanation. The run takes about two seconds, so it costs little to keep in every test run.

Check it worked

The run ends with 1 failed, and the line starting axe found: lists the five rule ids html-has-lang, image-alt, button-name, label and color-contrast, in some order. Nothing is reported about the Continue div or the missing focus outline.

Step 4 · Fix what axe found

Each fix is small, and each one uses plain HTML before reaching for ARIA. Rewrite the page with them in place:

Bash
cd ~/a11y-check-demo
cat > index.html <<'HTML'
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Your details · Larkfield Clinic</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header class="top">
    <button id="back" class="icon-button" type="button" aria-label="Back" onclick="history.back()">
      <svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M15 5l-7 7 7 7" fill="none" stroke="currentColor" stroke-width="2"/></svg>
    </button>
    <img src="logo.svg" width="120" height="32" alt="Larkfield Clinic">
  </header>
  <main>
    <h1>Your details</h1>
    <p class="service">Nurse appointment · Tue 9 Dec, 10:30</p>
    <form id="details" action="confirm.html" method="get">
      <label for="full-name">Full name</label>
      <input id="full-name" name="name" autocomplete="name">

      <label for="dob">Date of birth</label>
      <p class="hint" id="dob-hint">For example, 31 03 1985</p>
      <input id="dob" name="dob" inputmode="numeric" autocomplete="bday" aria-describedby="dob-hint">

      <label for="mobile">Mobile number</label>
      <input id="mobile" name="mobile" type="tel" autocomplete="tel">

      <label for="email">Email (optional)</label>
      <input id="email" name="email" type="email" autocomplete="email">

      <label class="check"><input id="reminder" name="reminder" type="checkbox"> Text me a reminder the day before</label>

      <div id="continue" class="button" onclick="document.getElementById('details').submit()">Continue</div>
    </form>
  </main>
</body>
</html>
HTML
cat >> style.css <<'CSS'

/* Hint text uses text-muted, which passes 4.5:1 on canvas */
.hint { color: #5A6270; }
CSS

What changed, problem by problem:

  • lang="en" on <html>. If a page mixes languages, for example a Yoruba or Swahili greeting above English instructions, mark that element with its own lang too, so the screen reader switches voice for it.
  • The back button gets aria-label="Back", and the icon inside gets aria-hidden="true" so it is not read as a separate thing. A visually hidden text span would work equally well.
  • The logo gets alt="Larkfield Clinic", the words it shows. If the clinic name were already in a heading next to it, alt="" would be right instead, so it is not read twice.
  • "Mobile number" becomes a real <label for="mobile">. Clicking the label now also puts the cursor in the field, which helps anyone with a small target to hit.
  • The hint uses text-muted, and aria-describedby ties it to the date field, so a screen reader reads the example after the label. axe did not ask for that second change. It is there because a hint that is never announced does not help anyone who cannot see it.

The Continue div and outline: none are deliberately still there.

Run the test again:

Bash
cd ~/a11y-check-demo
npx playwright test

Check it worked

The run ends with 1 passed, and no rule ids are printed. Reload the page in your browser: it looks the same apart from the hint, which is now a darker grey. Click the words "Mobile number" and the cursor lands in the mobile field.

Step 5 · Do a keyboard pass by hand

Now put the mouse aside. Many people use a keyboard, or a switch device or voice control that works like one, and every one of them needs to reach and see every control. Reload the page, click once on the empty background to be sure nothing is focused, then press Tab repeatedly and write down what happens. Use Shift+Tab to go back. In Safari on macOS, first turn on "Press Tab to highlight each item on a webpage" in Safari's Advanced settings, or Tab skips buttons. In Firefox on macOS, turn on Keyboard navigation in System Settings > Keyboard first, or use Chrome or Edge for this pass.

Write down, for each press: which control has focus, and whether you can see where focus is. You are looking for this order:

  1. Back
  2. Full name
  3. Date of birth
  4. Mobile number
  5. Email (optional)
  6. Text me a reminder the day before
  7. Continue

What you get instead:

  • Back shows the browser's focus ring. After that, focus moves into the four fields and the checkbox, but nothing shows it. You cannot tell which field you are in until you type. That is the outline: none on input:focus, and it fails WCAG 2.2 success criterion 2.4.7, Focus Visible.
  • After the checkbox, Tab leaves the page for the browser's address bar. Continue is never reached, so a keyboard user cannot book at all. A div with a click handler is not focusable and does not respond to Enter or Space. That fails 2.1.1, Keyboard.

axe passed this page a minute ago. It does not watch focus move and it cannot know that a div has an onclick, so neither problem is in its rule set. That is why the keyboard pass is a separate check, not a nice extra.

Check it worked

Your notes list seven stops in the expected order and two findings: no visible focus on the four fields and the checkbox, and Continue unreachable by keyboard. If you found Continue with Tab, check that you are looking at the div version of the page from the previous step.

Step 6 · Turn the keyboard pass into a test, then fix it

The hand pass found the problems. A test keeps them from coming back. This one presses Tab seven times and checks, at each stop, that the expected control has focus and that its outline is not none:

Bash
cd ~/a11y-check-demo
cat > tests/keyboard.spec.js <<'JS'
const { test, expect } = require('@playwright/test');
const { pathToFileURL } = require('node:url');
const path = require('node:path');

const PAGE = pathToFileURL(path.join(__dirname, '..', 'index.html')).href;
const TAB_ORDER = ['back', 'full-name', 'dob', 'mobile', 'email', 'reminder', 'continue'];

test('Tab reaches every control in order, with visible focus', async ({ page }) => {
  await page.goto(PAGE);
  for (const id of TAB_ORDER) {
    await page.keyboard.press('Tab');
    const control = page.locator(`#${id}`);
    await expect(control, `#${id} should have focus`).toBeFocused();
    await expect(control, `#${id} needs a visible focus outline`).not.toHaveCSS('outline-style', 'none');
  }
});
JS

Run only the new test:

Bash
cd ~/a11y-check-demo
npx playwright test tests/keyboard.spec.js

It fails at the second stop with #full-name needs a visible focus outline, after waiting a few seconds for a style that never arrives. Playwright stops at the first failed check in a test, so fix both problems now. Continue becomes a real <button type="submit">, which is focusable, works with Enter and Space and submits the form with no script. The .button class already resets the border and font, so it looks the same:

Bash
cd ~/a11y-check-demo
cat > index.html <<'HTML'
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Your details · Larkfield Clinic</title>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <header class="top">
    <button id="back" class="icon-button" type="button" aria-label="Back" onclick="history.back()">
      <svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M15 5l-7 7 7 7" fill="none" stroke="currentColor" stroke-width="2"/></svg>
    </button>
    <img src="logo.svg" width="120" height="32" alt="Larkfield Clinic">
  </header>
  <main>
    <h1>Your details</h1>
    <p class="service">Nurse appointment · Tue 9 Dec, 10:30</p>
    <form id="details" action="confirm.html" method="get">
      <label for="full-name">Full name</label>
      <input id="full-name" name="name" autocomplete="name">

      <label for="dob">Date of birth</label>
      <p class="hint" id="dob-hint">For example, 31 03 1985</p>
      <input id="dob" name="dob" inputmode="numeric" autocomplete="bday" aria-describedby="dob-hint">

      <label for="mobile">Mobile number</label>
      <input id="mobile" name="mobile" type="tel" autocomplete="tel">

      <label for="email">Email (optional)</label>
      <input id="email" name="email" type="email" autocomplete="email">

      <label class="check"><input id="reminder" name="reminder" type="checkbox"> Text me a reminder the day before</label>

      <button id="continue" class="button" type="submit">Continue</button>
    </form>
  </main>
</body>
</html>
HTML
cat >> style.css <<'CSS'

/* Keyboard focus: a clear accent ring, shown when the browser decides focus should be visible */
input:focus-visible,
button:focus-visible { outline: 3px solid #0F5E5A; outline-offset: 2px; }
CSS

The new rule has the same specificity as input:focus and comes later in the file, so it wins whenever :focus-visible matches. Browsers match it for keyboard focus, and for text fields on any focus, so the ring appears exactly when someone needs to see where they are. Delete the old input:focus { outline: none; } line when you tidy up; it no longer has any effect. Style keyboard focus with :focus-visible covers rings that work on every background.

Run both tests:

Bash
cd ~/a11y-check-demo
npx playwright test

Check it worked

The run ends with 2 passed. Reload the page and Tab through it: each field and the checkbox now show a teal ring two pixels outside their edge, and the seventh Tab lands on Continue. Press Enter there and the browser tries to open confirm.html with your answers in the address bar; it shows a "file not found" page because that screen is not part of this demo.

Step 7 · Do a screen reader pass with a script

The two tests prove that names, roles, order and focus are wired up. They do not prove the page makes sense when heard. A short scripted pass with a real screen reader catches what neither can: a label that is technically present but confusing, a hint read at the wrong moment, or an order that is logical in the code and odd out loud.

Pick one screen reader you can run:

  • NVDA on Windows, free from NV Access. Start it with Ctrl+Alt+N once installed. In browse mode, H moves to the next heading, F to the next form field and B to the next button. NVDA+F7 (Insert+F7 by default) lists headings, links and landmarks. Ctrl stops speech.
  • VoiceOver on macOS, built in. Cmd+F5 turns it on and off. VO means Control+Option held together: VO+Right Arrow moves to the next item, VO+U opens the rotor (lists of headings, form controls and landmarks) and VO+Space activates the current item.
  • TalkBack on Android, built in on most phones under Settings, then Accessibility. Swipe right for the next item, swipe left for the previous one and double-tap to activate. For a clinic whose patients mostly book on low-cost Android phones, this is the pass that matches them best. Run it in Chrome on the cheapest phone you can borrow, once the page is on a test address the phone can open.

Then follow the same script every time, and write down what you hear at each line rather than what you expected:

  1. Load the page. You hear the page title, "Your details · Larkfield Clinic".
  2. List the headings. There is one, "Your details", heading level 1.
  3. Move from the top, one item at a time. You hear "Back, button", then "Larkfield Clinic, image", then the heading, then the service line with the date and time.
  4. Move through the form with Tab (on a touch screen, swipe right to move to the next item). Each field announces its label and type: "Full name, edit text"; "Date of birth, edit text", followed by "For example, 31 03 1985"; "Mobile number" with a type such as "edit text" or "telephone"; "Email (optional), edit text"; "Text me a reminder the day before, checkbox, not checked".
  5. Tick the checkbox with Space (on a touch screen, double-tap it). You hear "checked".
  6. Reach Continue. You hear "Continue, button".
  7. Type a name such as Chukwuemeka Okafor or Nomvula Dlamini. Listen to how it is read back. With lang="en", an English voice reads it, sometimes oddly. That is not a page bug, but it tells you not to rely on a screen reader spelling out names the patient would need to check, and to show them as plain text on Confirm.

The exact wording differs between screen readers and versions ("edit text", "text field", "edit"). What matters is that every control has the right name, role and state, and nothing is announced that a sighted user would not need.

Check it worked

You have notes for all seven lines of the script, from one named screen reader and browser. Every control in lines 3 to 6 was announced with a name, and the date hint was read with the date field. Anything that surprised you is written down as a finding, even if axe and the keyboard test both pass.

Step 8 · Keep the checks running

The automated tests are only useful if they run on every change. Add them as the project's test command:

Bash
cd ~/a11y-check-demo
npm pkg set scripts.test="playwright test"
npm test

Now prove the axe test does its job: it should fail on a violation that was not there before. Keep a copy of the page, add an image with no alt to the end of it, and run the tests:

Bash
cd ~/a11y-check-demo
cp index.html index.backup.html
echo '<img src="logo.svg">' >> index.html
Bash
npm test

The axe test fails with axe found: image-alt, and the keyboard test still passes. Put the good page back and run the tests once more:

Bash
cd ~/a11y-check-demo
mv index.backup.html index.html
npm test

If you ever need to ship with a known violation while a fix is in progress, do not delete the test. Call .disableRules(['rule-id']) on the AxeBuilder for that one rule, with a comment linking the ticket, so the exception is visible in code review and easy to remove.

The manual passes need a home too. Save the checklist next to the tests, so whoever changes this screen next can repeat it:

Bash
cd ~/a11y-check-demo
cat > tests/manual-checklist.md <<'MD'
# Your details: manual accessibility checks

Run before releasing any change to this screen. Record the date, tester,
browser and screen reader for each pass.

## Keyboard (no mouse)
- [ ] Tab order: Back, Full name, Date of birth, Mobile number,
      Email (optional), reminder checkbox, Continue
- [ ] Focus is visible at every stop
- [ ] Space ticks the checkbox; Enter on Continue submits
- [ ] Nothing traps focus; Shift+Tab goes back the same way

## Screen reader (NVDA, VoiceOver or TalkBack)
- [ ] Page title is announced on load
- [ ] One heading, "Your details", level 1
- [ ] Back is "Back, button"; logo is "Larkfield Clinic, image"
- [ ] Each field announces its label; Date of birth also reads its hint
- [ ] Checkbox announces its label and checked state
- [ ] Continue is "Continue, button"
- [ ] Anything confusing heard aloud is logged as a finding

## Also check
- [ ] Zoom to 200 percent: nothing is cut off or overlaps
- [ ] One pass on a low-cost Android phone with TalkBack
MD

Check it worked

npm test prints 2 passed. During the regression check it printed 1 failed and 1 passed, with image-alt in the failure, and after the mv it passes again. tests/manual-checklist.md exists and lists the keyboard, screen reader and extra checks.

Step 9 · Clean up

When you have copied what you want to keep, remove the demo. npx playwright uninstall removes the browsers this Playwright install downloaded; leave that line out if other projects on this machine use Playwright.

Bash
cd ~/a11y-check-demo
npx playwright uninstall
cd ~
rm -rf ~/a11y-check-demo

Check it worked

ls ~/a11y-check-demo reports that there is no such file or directory.

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Digital Transformation

Get new tutorials

New tutorials, about twice a month.