Accessibility Testing with Playwright Assertions

Playwright has become one of the most popular testing frameworks for web applications. During it's...

Playwright has become one of the most popular testing frameworks for web applications. During it's rise, teams using it have been looking for quick and effective ways to test for accessibility.

Libraries like playwright-axe or @axe-core/playwright are a great starting point, but they only scratch the surface, giving very generic scans of your HTML content to give the lower 25% of accessibility issues. To truly validate the accessibility of the experience your users rely on, you need deeper, more intentional checks. That’s where Playwright’s accessibility assertions come in.

Using Playwright Axe

Playwright-Axe is a popular way to add automated accessibility scanning to your test suite. It integrates the Axe engine directly into Playwright tests, allowing you to run accessibility scans as part of your end‑to‑end workflow.

How to Use It

In your test setup function, (beforeEach, beforeAll) add in injectAxe(page) to get axe added into the page, and then whenever you are ready to do a scan of the page in a test case simply call checkA11y(page). Here is a code sample:

  //Injecting axe into the page object before every test case
  test.beforeAll(async ({ browser }) => {
    const context = await browser.newContext();
    page = await context.newPage();
    await page.goto('https://www.normalil.gov/');
    await injectAxe(page)
  });

  test('Axe Playwright Simple Scan - No customization', async () => {
    await checkA11y(page)
  });

What It Catches

Axe is great at identifying very basic accessibility regression issues such as:

• Missing or empty alt text
• Color contrast failures
• Incorrect or missing ARIA attributes
• Structural issues like missing landmarks
• Form fields without labels

These issues are the very bare minimum of issues you can catch, and can only generically check your content for issues. This is where Playwright Assertions can help take your tests beyond a simple accessibility scan.

Using Accessibility Assertions

Playwright includes a set of accessibility‑focused assertions that let you write specific regression tests that go beyond a generic scan of your page content. Let's take a look at the 3 assertions:

toHaveAccessibleDescription

This assertion checks that your element, has a proper associated description. For example, if you had an input field that had an aria-describedby tied to it with more instructions to help users understand the input, using this assertion can be used to ensure ARIA is being associated properly.

  test('Playwright assertion - toHaveAccessibleDescription()', async () => {
     await page.goto('https://accessibility.deque.com/contact-us-ga');
    
    const emailField = page.locator('input[name="firstname"]');

    await page.locator('input[type="submit"]').click();

    await expect(emailField).toHaveAccessibleDescription('Please complete this required field. (First Name). Press Tab to go to the input field to fix this error.');
  });

More Reading on Accessible Description: https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-description

toHaveAccessibleErrorMessage

This assertion checks that an error message is associated with an input field when an error is present. One key thing to note, this ONLY works with aria-errormessage. If you associated your error messages via aria-describedby then you'd want to use the previous assertion.

  test('Playwright assertion - toHaveAccessibleErrorMessage()', async () => {
     await page.goto('https://accessibility.deque.com/contact-us-ga');
    
    const emailField = page.locator('input[name="firstname"]');

    await page.locator('input[type="submit"]').click();

    await expect(emailField).toHaveAccessibleErrorMessage('Please complete this required field.');
  });

More Reading on Accessible Error Message: https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-error-message

toHaveAccessibleName

This assertion ensures that the object in question has the correct accessible name. This check can be very effective for complex tables with buttons, list of icon buttons, and ensuring that any action item has no misspelled words in the label!

  test('Playwright assertion - toHaveAccessibleName()', async () => {
    await page.goto('https://www.normalil.gov/');

    const rightSlideIcon = page.locator('.alwaysDisplayArrowNew.next');
    const leftSlideIcon = page.locator('.alwaysDisplayArrowNew.prev');

    await expect(leftSlideIcon).toHaveAccessibleName('Previous Slide'); 
    await expect(rightSlideIcon).toHaveAccessibleName('Next Slide');

  });

More Reading on Accessible Name: https://playwright.dev/docs/api/class-locatorassertions#locator-assertions-to-have-accessible-name

In Summary

Axe and other accessibility libraries are powerful, but it’s only the beginning. Automated scanners catch general accessibility issues but using Playwright’s accessibility assertions fill a larger gap in regression testing by:

• Testing the computed accessibility tree
• Ensuring accessible names, descriptions, and error messages are correct
• Preventing regressions as your product evolves

If your goal is to build interfaces that are truly accessible, not just “passing a scan,” assertions are the next step!

If you'd like to see a working example checkout the Automated Accessibility Example Library which houses a playwright example that show cases all the items talked about in this article.