Getting Started

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


// e2e/accessibility.test.js
const puppeteer = require('puppeteer')
const { levelAnalyze } = require('@level-ci/a11y-puppeteer')
 
;(async () => {
  const browser = await puppeteer.launch({ headless: true })
  const page = await browser.newPage()
  await page.goto('http://localhost:5000')
  await levelAnalyze(page)
  await browser.close()
})()

Prerequisites

Puppeteer version 20.7.4 or higher

Installation

Configure .npmrc and Install @level-ci/a11y-puppeteer 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-puppeteer


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

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

Setup

Level CI Puppeteer is an external package that must be imported in your Puppeteer scripts.

Option 1: Call levelAnalyze function right away

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


// e2e/google-accessibility.js
 
const puppeteer = require('puppeteer')
const { levelAnalyze } = require('@level-ci/a11y-puppeteer')
 
;(async () => {
  const browser = await puppeteer.launch()
  const page = await browser.newPage()
 
  await page.goto('https://www.google.com')
 
  // Run static accessibility analysis
  await levelAnalyze(page)
 
  await browser.close()
})()

Option 2: Using levelSetup for global setup

Call levelSetup before your tests or in a shared setup file:


// e2e/setup.ts
import { levelSetup } from '@level-ci/a11y-puppeteer'
 
levelSetup({
  reportPath: 'level-ci-reports-custom',
  stableSelectorAttributes: ['data-testid'],
})

Then use levelAnalyze in your scripts:


// e2e/demo.ts
import puppeteer from 'puppeteer'
import { levelAnalyze } from '@level-ci/a11y-puppeteer'
import './setup'
;(async () => {
  const browser = await puppeteer.launch()
  const page = await browser.newPage()
  await page.goto('/')
 
  const config = {}
  await levelAnalyze(page, config)
 
  await browser.close()
})()

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-puppeteer to the types section in your tsconfig.json:


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

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


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