README

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

Thanks

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

Usage no npm install needed!