pa11y-ci

library4.1.0jsnpmunverified

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.

testing devops

npm install pa11y-ci

github ↗package ↗

INSTALL

IMPORT

SIG · PA11Y-CI

pa11y-ci

testingjavascriptv4.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pa11yCi

✓ import pa11yCi from 'pa11y-ci';

✗ 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

✓ import { reporters } from 'pa11y-ci';

✗ const reporters = require('pa11y-ci/lib/reporters');

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)

✓ import { reporters } from 'pa11y-ci'; const jsonReporter = reporters.json;

✗ import { jsonReporter } from 'pa11y-ci';

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.

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

pa11y-ci --version

Debug

Known issues

breakingPa11y 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`).

affects: >=4.0.0

gotchaPa11y 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.

affects: 4.0.0

breakingVersion 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.

affects: >=4.0.0

gotchaWhen 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.

affects: 3.x

Errors

Common errors & fixes

Error: Could not find Chromium (or Chrome) in your system. Please install it or set the executablePath in the Puppeteer launch options.

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"})

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.

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.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

pa11yrequiredCore accessibility testing engine, upon which Pa11y CI is built.

puppeteerrequiredHeadless browser automation tool used by Pa11y for rendering and testing web pages.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/pa11y/pa11y-ci ↗

packagehttps://www.npmjs.com/package/pa11y-ci ↗