Skip to main content

Accessibility testing

Introduction​

Playwright can be used to test your application for many types of accessibility issues.

A few examples of problems this can catch include:

  • Text that would be hard to read for users with vision impairments due to poor color contrast with the background behind it
  • UI controls and form elements without labels that a screen reader could identify
  • Interactive elements with duplicate IDs which can confuse assistive technologies

The following examples rely on the com.deque.html.axe-core/playwright Maven package which adds support for running the axe accessibility testing engine as part of your Playwright tests.

Disclaimer​

Automated accessibility tests can detect some common accessibility problems such as missing or invalid properties. But many accessibility problems can only be discovered through manual testing. We recommend using a combination of automated testing, manual accessibility assessments, and inclusive user testing.

For manual assessments, we recommend Accessibility Insights for Web, a free and open source dev tool that walks you through assessing a website for WCAG 2.1 AA coverage.

Example accessibility tests​

Accessibility tests work just like any other Playwright test. You can either create separate test cases for them, or integrate accessibility scans and assertions into your existing test cases.

The following examples demonstrate a few basic accessibility testing scenarios.

Example 1: Scanning an entire page​

This example demonstrates how to test an entire page for automatically detectable accessibility violations. The test:

  1. Imports the com.deque.html.axe-core/playwright package
  2. Uses normal JUnit 5 @Test syntax to define a test case
  3. Uses normal Playwright syntax to open a browser and navigate to the page under test
  4. Invokes AxeBuilder.analyze() to run the accessibility scan against the page
  5. Uses normal JUnit 5 test assertions to verify that there are no violations in the returned scan results
import com.deque.html.axecore.playwright.*; // 1
import com.deque.html.axecore.utilities.axeresults.*;

import org.junit.jupiter.api.*;
import com.microsoft.playwright.*;

import static org.junit.jupiter.api.Assertions.*;

public class HomepageTests {
@Test // 2
void shouldNotHaveAutomaticallyDetectableAccessibilityIssues() throws Exception {
Playwright playwright = Playwright.create();
Browser browser = playwright.chromium().launch();
BrowserContext context = browser.newContext();
Page page = context.newPage();

page.navigate("https://your-site.com/"); // 3

AxeResults accessibilityScanResults = new AxeBuilder(page).analyze(); // 4

assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations()); // 5
}
}

Example 2: Configuring axe to scan a specific part of a page​

com.deque.html.axe-core/playwright supports many configuration options for axe. You can specify these options by using a Builder pattern with the AxeBuilder class.

For example, you can use AxeBuilder.include() to constrain an accessibility scan to only run against one specific part of a page.

AxeBuilder.analyze() will scan the page in its current state when you call it. To scan parts of a page that are revealed based on UI interactions, use Locators to interact with the page before invoking analyze():

public class HomepageTests {
@Test
void navigationMenuFlyoutShouldNotHaveAutomaticallyDetectableAccessibilityViolations() throws Exception {
page.navigate("https://your-site.com/");

page.locator("button[aria-label=\"Navigation Menu\"]").click();

// It is important to waitFor() the page to be in the desired