expect-axe-playwright

Expect matchers to perform Axe accessibility tests in your Playwright tests.

Installation

npm

npm install expect-axe-playwright

Yarn

yarn add expect-axe-playwright

Usage

// playwright.config.ts
import { expect } from '@playwright/test'
import matchers from 'expect-axe-playwright'

expect.extend(matchers)

Why do I need it?

This project was inspired by axe-playwright which did a great job of integrating the axe-core library with some simple wrapper functions. However, the API is not as elegant for testing as would be preferred. That's where expect-axe-playwright comes to the rescue with the following features.

Direct integration with the expect API for simplicity and better error messaging.
Automatic Axe script injection.
Auto-retry until timeout.
Works with pages, frames, and locators.
HTML report with full violation details.
Project-level option configuration.

Here are a few examples:

await expect(page).toBeAccessible() // Page
await expect(page.locator('#foo')).toBeAccessible() // Locator
await expect(page.frameLocator('iframe')).toBeAccessible() // Frame locator

API Documentation

`toBeAccessible`

This function checks if a given page, frame, or element handle is accessible.

You can test the entire page:

await expect(page).toBeAccessible()

Or pass a locator to test part of the page:

await expect(page.locator('#my-element')).toBeAccessible()

Axe run options

You can configure options that should be passed to aXe at the project or assertion level.

To configure a single assertion to use a different set of options, pass an object with the desired arguments to the matcher.

await expect(page).toBeAccessible({
  rules: {
    'color-contrast': { enabled: false },
  },
})

To configure the entire project to use a different set of options, specify options in use.axeOptions in your Playwright config file.

// playwright.config.ts
import { PlaywrightTestConfig } from '@playwright/test'

const config: PlaywrightTestConfig = {
  use: {
    axeOptions: {
      rules: {
        'color-contrast': { enabled: false },
      },
    },
  },
}

export default config

Report options

You can configure options that should be passed to the aXe HTML reporter at the assertion level.

await expect(page.locator('#my-element')).toBeAccessible({
  filename: 'my-report.html',
})

This is particularly useful if you need to produce multiple aXe reports within the same test as it would otherwise keep replacing the same report every time you run the assertion.

Thanks

axe-playwright for the inspiration and groundwork laid for using Axe with Playwright.

gabalafou/expect-axe-playwright