---
title: Accessibility Testing with Playwright and axe-core
description: Check pages for WCAG A and AA violations with @axe-core/playwright inside
  your Playwright Test suite, running on TestingBot's cloud browsers.
source_url:
  html: https://testingbot.com/support/accessibility/web/playwright
  md: https://testingbot.com/support/accessibility/web/playwright.md
---

# Playwright and axe-core

[@axe-core/playwright](https://github.com/dequelabs/axe-core-npm/tree/develop/packages/playwright) is Deque's official package for running the axe-core accessibility engine from a Playwright test. Add it to your existing Playwright Test suite and point the suite at TestingBot to scan the pages your tests reach on our cloud browsers.

The scan runs from your test code: the package injects axe-core into the page and returns the results to your test. It uses the axe-core version installed in your project, not the version the TestingBot [scheduled scans](https://testingbot.com/support/accessibility/web/scheduled) use, so results can differ slightly between the two.

## Installation

```bash
npm i -D @playwright/test @axe-core/playwright
```

## Connect to TestingBot

Set `connectOptions` in `playwright.config.js` so every test opens its browser on TestingBot. The [Playwright Test guide](https://testingbot.com/support/web-automate/playwright/playwright-test) explains the options and how to run against several browsers.

```javascript
import { defineConfig } from '@playwright/test'

const capabilities = {
  browserName: 'chrome',
  browserVersion: 'latest',
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  }
}

export default defineConfig({
  testDir: './tests',
  projects: [
    {
      name: 'chrome',
      use: {
        browserName: 'chromium',
        connectOptions: {
          wsEndpoint: `wss://cloud.testingbot.com/playwright?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
        }
      }
    }
  ]
})
```

## Example test

This test opens a page, runs axe-core with the WCAG 2.0 and 2.1 level A and AA rules, and fails when there are violations.

```javascript
import { test, expect } from '@playwright/test'
import AxeBuilder from '@axe-core/playwright'

test('home page has no automated WCAG A/AA violations', async ({ page }) => {
  await page.goto('https://example.com/')

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
    .analyze()

  expect(results.violations).toEqual([])
})
```

Run it with `npx playwright test`. When the test fails, the diff lists each violated rule with the elements that failed it.

A passing test means axe-core found no violations of the rules it ran on that page state. It does not mean the page is accessible: see [what automated checks don't catch](https://testingbot.com/support/accessibility/web/manual-checks).

## Choosing rules

- `withTags([...])` runs only rules with these tags, for example `wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa`, `wcag22aa` or `best-practice`.
- `disableRules(['color-contrast'])` skips rules you check another way.
- Without `withTags`, axe-core runs its default rule set. In axe-core 4.11 the WCAG 2.2 rule `target-size` is off by default; add the `wcag22aa` tag to run it.

## Scanning part of a page

Use `include()` and `exclude()` with CSS selectors, for example to leave out a third-party widget you cannot fix:

```javascript
const results = await new AxeBuilder({ page })
  .include('main')
  .exclude('#chat-widget')
  .analyze()
```

To check a dialog or menu, open it in your test first and then run the scan: axe-core only checks what is in the page at that moment.

## Saving the report

Attach the full result to the Playwright HTML report so you can inspect it after a CI run:

```javascript
await test.info().attach('accessibility-scan-results', {
  body: JSON.stringify(results, null, 2),
  contentType: 'application/json'
})
```

## Looking for more help?

Have questions or need more information? Reach out via email or Slack.

[Email us](https://testingbot.com/contact/new) [Join our Slack](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)
