Skip to main content
Version: v5

Testing with Playwright

Use the AudioEye Accessibility Testing SDK Playwright package to run accessibility checks inside your Playwright end-to-end tests.

Before you start​

Complete the package-manager and entitlement-token setup in getting started before installing this package.

Requirements​

  • Node.js 20, 22, or 24
  • @playwright/test version 1.39.0 or later
  • a working Playwright test project
  • an AudioEye entitlement token configured through your package manager

If your project does not already use Playwright, start with the Playwright installation guide.

Install​

npm install -D @audioeye/testing-sdk-playwright @playwright/test

If Playwright browser binaries are not installed yet, install them:

npx playwright install

Choose a setup style​

The SDK exposes Playwright fixtures named accessibility and a11y. You can use either name.

You have two common setup options:

  1. Use AudioEye's extended test runner directly for the fastest setup.
  2. Create your own shared fixture file if your team already centralizes Playwright fixtures.

If you're onboarding a project for the first time, start with using the extended test runner directly.

Quick start: first passing test​

This example gives you the shortest path to a working test.

Create a test file like tests/accessibility.spec.ts:

tests/accessibility.spec.ts
import { test, expect } from '@audioeye/testing-sdk-playwright';

test('homepage has no level A or AA accessibility issues', async ({ page, accessibility }) => {
  await page.setContent(`
    <main>
      <h1>Welcome</h1>
      <button type="button">Start free trial</button>
      <a href="/learn-more">Learn more</a>
      <img src="logo.png" alt="AudioEye company logo" />
    </main>
  `);

  const results = await accessibility.evaluate();

  expect(results.conformanceLevel('AA').resultCodes).toEqual([]);
});

Run the test with Playwright:

npx playwright test tests/accessibility.spec.ts

This verifies that:

  • the package installed successfully
  • your entitlement token is configured correctly
  • Playwright can run the test
  • the AudioEye fixture is available in the test context
  • the SDK can evaluate the page and return results

First failing test​

A failing example is useful when you want to confirm the SDK is actively catching issues.

tests/accessibility-failing.spec.ts
import { test, expect } from '@audioeye/testing-sdk-playwright';

test('example failing test', async ({ page, accessibility }) => {
  await page.setContent(`
    <main>
      <h1>Welcome</h1>
      <img src="hero.png" alt="image" />
    </main>
  `);

  const results = await accessibility.evaluate();

  expect(results.resultCodes).toContain('Img_Name_WeakName');
});

Setup option 1: use the extended test runner directly​

This is the simplest setup. Import test from @audioeye/testing-sdk-playwright and expect from @playwright/test.

tests/example.spec.ts
import { test } from '@audioeye/testing-sdk-playwright';
import { expect } from '@playwright/test';

test("example Playwright test using AudioEye's Testing SDK", async ({ page, accessibility }) => {
  await page.goto('http://localhost:3000/');

  const results = await accessibility.evaluate();

  expect(results.resultCodes).toEqual([
    // add your expected rule codes here
  ]);
});

Use this approach when:

  • you are getting started quickly
  • you do not already have a custom shared fixture setup
  • you want the least amount of project wiring

Setup option 2: add AudioEye fixtures to your existing test runner​

If your Playwright project already has a shared fixture file, extend that file with AudioEye's fixtures.

tests/fixtures.ts
import { type AudioEyeFixtures, AudioEyeA11y } from '@audioeye/testing-sdk-playwright';
import { test as base } from '@playwright/test';

export const test = base.extend<AudioEyeFixtures>({
  accessibility: async ({ page }, use) => {
    await use(new AudioEyeA11y(page));
  },
  a11y: async ({ accessibility }, use) => {
    await use(accessibility);
  },
});
tests/example.spec.ts
import { expect } from '@playwright/test';

import { test } from './fixtures';

test("example Playwright test using AudioEye's Testing SDK", async ({ page, accessibility }) => {
  await page.goto('http://localhost:3000/');

  const results = await accessibility.evaluate();

  expect(results.resultCodes).toEqual([
    // add your expected rule codes here
  ]);
});

Use this approach when:

  • you already extend Playwright fixtures for authentication, seeded data, or page objects
  • you want one shared test export across your project
  • you want AudioEye integrated into your existing fixture architecture

Usage patterns​

Evaluate the whole page​

Run the SDK against the full rendered page:

import { test } from '@audioeye/testing-sdk-playwright';
import { expect } from '@playwright/test';

test('checks the whole page', async ({ page, accessibility }) => {
  await page.goto('http://localhost:3000/');

  const results = await accessibility.evaluate();

  expect(results.conformanceLevel('AA').resultCodes).toEqual([]);
});

Evaluate a specific section​

Pass a Playwright locator when you want to scope evaluation to one part of the page.

import { test } from '@audioeye/testing-sdk-playwright';
import { expect } from '@playwright/test';

test('checks a specific region', async ({ page, accessibility }) => {
  await page.goto('http://localhost:3000/');

  const results = await accessibility.evaluate(page.locator('.navbar__right'));

  expect(results.conformanceLevel('A').resultCodes).toEqual(['Link_VisualIndicator_Missing', 'Svg_Name_Missing']);
});

Filter by conformance level​

Use conformanceLevel to focus assertions on A, AA, or AAA.

import { test } from '@audioeye/testing-sdk-playwright';
import { expect } from '@playwright/test';

test('filters results by conformance level', async ({ page, accessibility }) => {
  await page.goto('http://localhost:3000/');

  const results = await accessibility.evaluate();

  expect(Object.keys(results.conformanceLevel('AA').resultsGroupedByWcagSuccessCriteriaLevel)).toEqual(['A']);
  expect(Object.keys(results.resultsGroupedByWcagSuccessCriteriaLevel)).toEqual(['A', 'AAA']);
});

For most teams, this sequence works well:

  1. Start with a single passing test using page.setContent(...).
  2. Add a failing test to confirm the SDK catches known issues.
  3. Point the test at a real local page with page.goto(...).
  4. Add accessibility assertions to an existing smoke test or critical user flow.
  5. Reuse fixtures across your Playwright suite if needed.

This approach helps you separate installation problems from application-specific issues.

SDK API​

evaluate​

Evaluate the accessibility of the page or element using AudioEye's rule suite.

import { test } from '@audioeye/testing-sdk-playwright';
import { expect } from '@playwright/test';

test("example Playwright test using AudioEye's Testing SDK", async ({ page, accessibility }) => {
  await page.goto('http://localhost:3000/');

  const accessibilityResults = await accessibility.evaluate();
  expect(accessibilityResults.resultCodes).toEqual(expect.any(Array));
});

Parameters​

› locator (Locator)

The locator to evaluate. If omitted, the SDK evaluates the root of the page.

Returns​

evaluate returns a class instance of type A11yResults.

A11yResults API​

conformanceLevel​

Filter the accessibility results by conformance level. Valid values are A, AA, or AAA. Higher conformance levels include lower levels.

const results = accessibilityResults.conformanceLevel('AA');

Parameters​

› level (String)

The conformance level to filter by: A, AA, or AAA.

Returns​

A new instance of A11yResults.

resultCodes​

Get the result codes for the accessibility results as an array of strings.

const resultCodes = accessibilityResults.resultCodes;
// ['Img_Name_WeakName']

Returns​

An array of strings representing the result codes.

resultsGroupedByWcagSuccessCriteriaLevel​

Group the accessibility results by WCAG success criteria level.

accessibilityResults.resultsGroupedByWcagSuccessCriteriaLevel;
// { A: [ ... ], AA: [ ... ], AAA: [ ... ] }

Returns​

An object containing the test results grouped by WCAG success criteria level.

Troubleshooting​

The package will not install​

Make sure you completed the entitlement-token configuration in getting started.

Playwright is installed but tests will not launch​

Install Playwright's browser binaries:

npx playwright install

I need to test authenticated flows​

Use your existing Playwright login strategy, then call accessibility.evaluate() after the page reaches the state you want to verify.

I need help understanding which rules can run in this environment​

See How Rules Work in Different Testing Scenarios.