Getting Started

The @level-ci/a11y-playwright package enables accessibility testing in your Playwright workflow.
It lets you run static page analysis and generate detailed reports of accessibility violations based on WCAG guidelines and ACT rules.


// playwright/e2e/my-test.spec.js
const { test } = require('@playwright/test')
const { levelAnalyze } = require('@level-ci/a11y-playwright')
 
test('example test', async ({ page }) => {
  await page.goto('http://localhost:5000')
  await levelAnalyze(page)
})

Prerequisites

Playwright version 1.57.0 or higher

Installation

Configure .npmrc and Install @level-ci/a11y-playwright package

Run the following commands in the root of your project to configure the registry and authentication.


npm config --location project set @level-ci:registry https://npm.levelaccess.net/level-ci/
npm config --location project set //npm.levelaccess.net/level-ci/:_authToken=\${CLOUDSMITH_TOKEN}

Declare a Cloudsmith Token


export CLOUDSMITH_TOKEN=MY_CLOUDSMITH_TOKEN

By using the CLOUDSMITH_TOKEN you will be able to install the needed package.

Install the package.

You can do this by using either npm or yarn.


npm install --save-dev @level-ci/a11y-playwright


yarn add -D @level-ci/a11y-playwright

This will add @level-ci/a11y-playwright to the dev dependencies in package.json.

Setup

Level CI App Playwright is an external package that must be imported in your Playwright tests.

Option 1: Call levelAnalyze function right away

Import @level-ci/a11y-playwright and call the levelAnalyze function:


// playwright/e2e/google-accessibility.spec.js
 
const { test } = require('@playwright/test')
const { levelAnalyze } = require('@level-ci/a11y-playwright')
 
test('Google basic example', async ({ page }) => {
  // Visit a target page
  await page.goto('https://www.google.com')
 
  // Run static accessibility analysis
  await levelAnalyze(page)
})

Option 2: Using levelSetup for global setup


// playwright/fixtures.ts
import { test as base } from '@playwright/test'
import { levelAnalyze, levelSetup } from '@level-ci/a11y-playwright'
 
export const test = base.extend({
  levelCiAnalyze: async ({}, use) => {
    levelSetup({
      reportPath: 'level-ci-reports-custom',
      stableSelectorAttributes: ['data-testid'],
    })
 
    await use(levelAnalyze)
  },
})

Then you will be able to use it in tests:


// playwright/demo.spec.ts
import { expect } from '@playwright/test'
import { test } from '../fixtures'
 
test.describe('test', () => {
  test('runs Level CI analysis on the home page', async ({
    levelCiAnalyze,
    page,
  }) => {
    await page.goto('/')
 
    const config = {}
    await levelCiAnalyze(page, config)
  })
})

Note: For more details see levelSetup usage.

Running levelAnalyze will create a report folder, where all of the issues data will be contained. File structure for the directory enables issue deduplication, which helps in achieving faster scans.

TypeScript Support

If you are using TypeScript, add @level-ci/a11y-playwright to the types section in your tsconfig.json:


{
  "compilerOptions": {
    "types": ["playwright", "@level-ci/a11y-playwright"]
  }
}

If you are not using TypeScript, you can still enable autocompletion by adding type references at the top of your test files:


/// <reference types="playwright" />
 
/// <reference types="@level-ci/a11y-playwright" />