Pa11y CI

4.1.0 · active · verified Tue Apr 21

Pa11y CI is an accessibility testing tool built upon the core Pa11y library, specifically engineered for integration into Continuous Integration (CI) workflows. It facilitates automated auditing of web applications against WCAG standards by scanning a defined list of URLs or a sitemap. The current stable version is `4.1.0`, actively maintained with updates often synchronizing with its upstream dependencies like Pa11y and Puppeteer. Its key differentiators include its robust command-line interface, making it ideal for CI environments, and its flexible configuration system that supports both JSON and JavaScript files. This allows for fine-grained control over testing parameters, including parallel execution, browser contexts, and specific Pa11y options per URL, enabling comprehensive and efficient accessibility validation. It leverages a headless Chromium browser to perform accurate, real-world accessibility checks.

Common errors

```
Error: Could not find Chromium (or Chrome) in your system. Please install it or set the executablePath in the Puppeteer launch options.
```
cause Puppeteer, used internally by Pa11y, could not locate a compatible browser. This is common in CI environments, Docker containers, or specific Linux distributions where Chrome/Chromium is not installed or discoverable in standard paths.

fix Ensure system dependencies for Chromium are installed (e.g., `apt-get install chromium-browser` on Debian/Ubuntu). Alternatively, specify `defaults.chromeLaunchConfig.executablePath` in your `.pa11yci.json` or `.js` config file, pointing to the correct browser executable.
```
npm ERR! EBADENGINE Unsupported engine for pa11y-ci@4.0.0: wanted: {"node": ">=20.0.0 <20.18.1"} (current: {"node": "20.17.0", "npm": "10.2.4"})
```
cause Attempting to install or use Pa11y CI version 4.0.0 with a Node.js version in the range of `20.0.0` to `20.18.0`, which had a temporary `cheerio` dependency conflict.

fix Update your `pa11y-ci` package to version `4.0.1` or newer. If you cannot update `pa11y-ci`, then update your Node.js version to `20.18.1` or later.
```
Pa11y CI requires a stable (even-numbered) Node.js version of 20 or above.
```
cause Running Pa11y CI version 4.0.0 or later with an older or unsupported Node.js version (e.g., Node.js 18 or an odd-numbered version).

fix Upgrade your Node.js environment to a stable (even-numbered) version 20 or higher. Use `nvm` to switch to `nvm use 20` or `nvm install 20` if necessary.

Warnings

breaking Pa11y CI v4.0.0 and above explicitly require a stable (even-numbered) Node.js version of 20 or above.
Fix: Upgrade your Node.js environment to version 20 or higher to ensure compatibility. Use tools like `nvm` to manage Node.js versions effectively (e.g., `nvm install 20 && nvm use 20`).
gotcha Pa11y CI `4.0.0` could cause `EBADENGINE` warnings/errors during installation when used with Node.js versions between `20.0.0` and `<20.18.1` due to an updated `cheerio` dependency.
Fix: Upgrade Pa11y CI to `4.0.1` or later, which reintroduces compatibility, or ensure your Node.js version is `20.18.1` or higher.
breaking Version 4.0.0 introduced major dependency upgrades to Pa11y 9 and Puppeteer 24. These upgrades may involve changes in underlying behavior, default configurations, or removal of deprecated options.
Fix: Review the official migration guide for Pa11y CI `v4.0.0` and the changelogs for Pa11y `v9` and Puppeteer `v24` to adapt your existing configurations or test scripts.
gotcha When using Pa11y CI v3 with Ubuntu versions above `20.04`, Puppeteer may fail to find the Chrome executable, resulting in errors during test execution.
Fix: Explicitly define the `defaults.chromeLaunchConfig.executablePath` in your Pa11y CI configuration file, pointing to the correct Chrome executable path (e.g., `/usr/bin/google-chrome`), or upgrade to Pa11y CI v4, which resolves this issue.

Install

npm install pa11y-ci npm
yarn add pa11y-ci yarn
pnpm add pa11y-ci pnpm

Imports

pa11yCi
wrong:
```
import { pa11yCi } from 'pa11y-ci';
```
correct:
```
import pa11yCi from 'pa11y-ci';
```
The primary programmatic entry point for Pa11y CI is an async function exported as the default. This allows for direct programmatic execution of the accessibility tests, mirroring CLI functionality.
reporters
wrong:
```
const reporters = require('pa11y-ci/lib/reporters');
```
correct:
```
import { reporters } from 'pa11y-ci';
```
Pa11y CI bundles several built-in reporters (e.g., 'cli', 'json', 'html'). The `reporters` object, containing these reporter functions, can be imported for programmatic use, such as custom result processing.
jsonReporter (example)
wrong:
```
import { jsonReporter } from 'pa11y-ci';
```
correct:
```
import { reporters } from 'pa11y-ci'; const jsonReporter = reporters.json;
```
Individual reporters can be accessed from the `reporters` object after importing. While direct deep imports from `pa11y-ci/lib/reporters` might work, it's generally discouraged in favor of accessing them via the main `reporters` export.

Quickstart

Demonstrates configuring Pa11y CI with a JavaScript file for multiple URLs and executing it via the command line, including per-URL overrides.

/* .pa11yci.js */
module.exports = {
  defaults: {
    timeout: 5000,
    viewport: {
      width: 1280,
      height: 720
    },
    // Example: Use the 'json' reporter for CI integration
    reporter: 'json'
  },
  urls: [
    'https://pa11y.org/',
    {
      url: 'https://pa11y.org/contributing',
      // Override default timeout for a potentially slow page
      timeout: 10000,
      // Example of per-URL pa11y configuration
      actions: ['click element #nav-menu-button', 'wait for path to be /contributing']
    },
    'https://example.com' // Another URL to test
  ]
};

// To run this configuration from your terminal:
// npm install -g pa11y-ci
// pa11y-ci --config .pa11yci.js

// If installed locally:
// npm install pa11y-ci
// npx pa11y-ci --config .pa11yci.js

view raw JSON →