Nicely Pruned Marigolds

    expect-axe-playwright
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.0 • Public • Published

    expect-axe-playwright

    Build npm version changesets

    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.

    Install

    npm i expect-axe-playwright

    DownloadsWeekly Downloads

    121

    Version

    2.2.0

    License

    ISC

    Unpacked Size

    20.3 kB

    Total Files

    14

    Last publish

    Collaborators

    • widen-npm