{"id":15365,"library":"pa11y-ci","title":"Pa11y CI","description":"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.","status":"active","version":"4.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/pa11y/pa11y-ci","tags":["javascript","a11y","accessibility","analysis","aria","audit","automation","axe","axe-core"],"install":[{"cmd":"npm install pa11y-ci","lang":"bash","label":"npm"},{"cmd":"yarn add pa11y-ci","lang":"bash","label":"yarn"},{"cmd":"pnpm add pa11y-ci","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core accessibility testing engine, upon which Pa11y CI is built.","package":"pa11y","optional":false},{"reason":"Headless browser automation tool used by Pa11y for rendering and testing web pages.","package":"puppeteer","optional":false}],"imports":[{"note":"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.","wrong":"import { pa11yCi } from 'pa11y-ci';","symbol":"pa11yCi","correct":"import pa11yCi from 'pa11y-ci';"},{"note":"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.","wrong":"const reporters = require('pa11y-ci/lib/reporters');","symbol":"reporters","correct":"import { reporters } from 'pa11y-ci';"},{"note":"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.","wrong":"import { jsonReporter } from 'pa11y-ci';","symbol":"jsonReporter (example)","correct":"import { reporters } from 'pa11y-ci'; const jsonReporter = reporters.json;"}],"quickstart":{"code":"/* .pa11yci.js */\nmodule.exports = {\n  defaults: {\n    timeout: 5000,\n    viewport: {\n      width: 1280,\n      height: 720\n    },\n    // Example: Use the 'json' reporter for CI integration\n    reporter: 'json'\n  },\n  urls: [\n    'https://pa11y.org/',\n    {\n      url: 'https://pa11y.org/contributing',\n      // Override default timeout for a potentially slow page\n      timeout: 10000,\n      // Example of per-URL pa11y configuration\n      actions: ['click element #nav-menu-button', 'wait for path to be /contributing']\n    },\n    'https://example.com' // Another URL to test\n  ]\n};\n\n// To run this configuration from your terminal:\n// npm install -g pa11y-ci\n// pa11y-ci --config .pa11yci.js\n\n// If installed locally:\n// npm install pa11y-ci\n// npx pa11y-ci --config .pa11yci.js\n","lang":"javascript","description":"Demonstrates configuring Pa11y CI with a JavaScript file for multiple URLs and executing it via the command line, including per-URL overrides."},"warnings":[{"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`).","message":"Pa11y CI v4.0.0 and above explicitly require a stable (even-numbered) Node.js version of 20 or above.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"3.x"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Could not find Chromium (or Chrome) in your system. Please install it or set the executablePath in the Puppeteer launch options."},{"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.","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.","error":"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\"})"},{"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.","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).","error":"Pa11y CI requires a stable (even-numbered) Node.js version of 20 or above."}],"ecosystem":"npm"}