Automating UI Accessibility Checks with WCAG 2.2 Scenarios and PlaywrightArticle · digest for November 5
Engineering scene of a UI accessibility audit showing modal keyboard navigation and WCAG 2.2 test reports on a laptop screen.
Article4 sections≈ 7 min

Automating UI Accessibility Checks with WCAG 2.2 Scenarios and Playwright

If you have ever set up an accessibility (a11y) audit in a frontend repository, you probably started with the standard toolkit: the eslint-plugin-jsx-a11y linter, the axe-core plugin, and a Lighthouse report in CI/CD. It seems like you get a green badge and the release is ready. Yet the moment a blind user with a screen reader or someone navigating purely by keyboard opens the page, problems begin.

Focus falls into invisible layers, closing a modal throws the cursor back to the top of the document, and tabs switch via Tab instead of arrow keys. Why do automated tools miss these basic issues?

Let's break down how this works and see how the UK team at TetraLogical approached automating over 95% of WCAG 2.2 requirements using a combination of BDD scenarios and the headless Playwright browser.

The Blind Spot of Static Linters: Why 60% of Bugs Slip Past CI

The problem with traditional DOM scanners and linters lies in their architectural limitations. Tools like axe-core or Pa11y analyze a static snapshot of the markup at a single point in time. They are great at catching baseline defects:

  • A missing alt attribute on an <img> tag;
  • Insufficient contrast ratio between text and background;
  • Broken heading hierarchy from h1 to h6;
  • A missing text label on a button or input field.

However, such static errors make up only a third of all accessibility barriers. The remaining issues appear exclusively in motion—during interactive use of the interface.

A static analyzer cannot check whether focus is trapped inside an open popup (keyboard focus trap) until that popup is clicked open. It does not know where focus will return after pressing Escape—to the trigger button or to the root of the page. It will not verify whether a screen reader announces a dynamic cart update via aria-live.

Until recently, the only way out was slow manual testing with screen readers (NVDA, JAWS, VoiceOver). Embedding a human tester into every pull request of a design system is unrealistic. That gap is what the open-source accessible-components-library by TetraLogical closes.

TetraLogical Library Architecture: Five WCAG 2.2 Areas and 8 Core Components

TetraLogical engineers identified 8 fundamental UI components that form the building blocks of any design system:

  • Accordion: expandable panels with headings and button roles;
  • Breadcrumbs: a navigation trail with nav semantics and aria-current="page";
  • Dialog / Modal: isolated modal windows with focus containment;
  • Disclosure: a single button to show and hide a block;
  • Pagination: accessible navigation across list pages;
  • Tabs: content switching following the official ARIA tabs pattern;
  • Text Input: forms with associated labels and error messages;
  • Textarea: input fields with a dynamic character counter.

All WCAG 2.2 criteria are broken down into five practical areas:

  1. Adaptability: adaptability when zooming text up to 200% without losing functionality and reflow without horizontal scrolling at 320px width (WCAG 1.4.10).
  2. Keyboard: access to all elements without a mouse (WCAG 2.1.1), no keyboard traps (WCAG 2.1.2), and a visible, high-contrast focus indicator (WCAG 2.4.7).
  3. Assistive Technology: strict semantics for roles and states (aria-expanded, aria-selected, aria-controls), and change announcements via live regions.
  4. Colour and Contrast: minimum text contrast of 4.5:1 for normal text and 3:1 for large text.
  5. Input Assistance: highlighting errors via aria-invalid="true" and linking them to hints via aria-describedby.

From Gherkin BDD Scenarios to Playwright Steps: How the Test Runner Works

Instead of writing scattered tests, TetraLogical developers wrote requirements in Gherkin. This lets designers, accessibility managers, and engineers collaborate using a single, clear vocabulary.

Scenarios live in .feature files. The @automatic tag marks checks handled entirely by the test runner, while @manual separates out criteria that require subjective human judgment.

Here is a snippet of the specification for testing modal focus isolation from the TetraLogical GitHub repository:

@dialog @keyboard @2.1.2 @a @automatic
Feature: Dialog — Keyboard Trap and Focus Management

  Background:
    Given I load the sample "components/dialog/examples/modal.html"

  Scenario: Tab key cycles focus within the active dialog
    When I click the button "Open Dialog"
    Then the element "#modal-dialog" should be visible
    And the focus should be on the element "#dialog-first-input"
    When I press "Tab" until reaching the last focusable element
    And I press "Tab"
    Then the focus should be on the element "#dialog-close-button"

  @dialog @keyboard @escape @automatic
  Scenario: Escape key dismisses the dialog and returns focus to trigger
    When I click the button "Open Dialog"
    And I press "Escape"
    Then the element "#modal-dialog" should not be visible
    And the focus should be on the element "#open-dialog-trigger"

The step definitions layer translates Gherkin statements directly into asynchronous Playwright API calls:

import { Given, When, Then } from '@cucumber/cucumber';
import { expect } from '@playwright/test';
import { AccessibilityWorld } from '../support/world';

Given('I load the sample {string}', async function (this: AccessibilityWorld, url: string) {
  await this.page.goto(url);
  await this.page.waitForLoadState('networkidle');
});

When('I press {string}', async function (this: AccessibilityWorld, key: string) {
  await this.page.keyboard.press(key);
});

Then('the focus should be on the element {string}', async function (this: AccessibilityWorld, selector: string) {
  const targetElement = this.page.locator(selector);
  await expect(targetElement).toBeFocused();
});

If you have already explored how the TetraLogical component library is built, you know that the browser handles part of basic focus management on its own. Still, TetraLogical's scenarios ensure that under any composition of custom buttons and nested fields, focus never gets lost in the document tree.

Integrating into the CI/CD Pipeline: Automated Test Execution

Integrating the test suite into a project requires Node.js and installing the runners:

npm install --save-dev @playwright/test @cucumber/cucumber ts-node typescript
npx playwright install --with-deps chromium

The cucumber.js configuration file restricts execution to automated tests only:

module.exports = {
  default: {
    paths: ['features/**/*.feature'],
    require: ['features/step_definitions/**/*.ts', 'features/support/**/*.ts'],
    requireModule: ['ts-node/register'],
    format: ['summary', 'html:reports/accessibility-report.html'],
    tags: '@automatic and not @manual',
    parallel: 2
  }
};

The AccessibilityWorld helper class creates the Playwright browser context:

import { setWorldConstructor, World, IWorldOptions, Before, After } from '@cucumber/cucumber';
import { Browser, BrowserContext, Page, chromium } from 'playwright';

export class AccessibilityWorld extends World {
  browser!: Browser;
  context!: BrowserContext;
  page!: Page;

  constructor(options: IWorldOptions) {
    super(options);
  }
}

setWorldConstructor(AccessibilityWorld);

Before(async function (this: AccessibilityWorld) {
  this.browser = await chromium.launch({ headless: true });
  this.context = await this.browser.newContext({ viewport: { width: 1280, height: 720 } });
  this.page = await this.context.newPage();
});

After(async function (this: AccessibilityWorld) {
  await this.page.close();
  await this.context.close();
  await this.browser.close();
});

Running it in a CI pipeline takes npx cucumber-js. If a developer forgets to restore focus after closing a modal or breaks Tab key cycling, the pull request build fails immediately with the exact WCAG criterion violated. That saves dozens of hours of manual testing and shields the UI from hidden regressions.

Want a deep diveVotes help us choose what to break down in detail. This material has 0 votes.
Sources · 3