Pa11y

Pa11y is your automated accessibility testing pal. It runs accessibility tests on your pages via the command line or Node.js, so you can automate your testing process.

[![NPM version][shield-npm]][info-npm] [![Node.js version support][shield-node]][info-node] [![Build status][shield-build]][info-build] [![LGPL-3.0-only licensed][shield-license]][info-license]

On the command line:

pa11y https://example.com

In JavaScript:

const pa11y = require('pa11y');

pa11y('https://example.com').then((results) => {
    // Use the results
});

Requirements

Pa11y 9 requires [Node.js][node] 20, 22, or 24. An older version of Node.js can be used with Pa11y 8 or below.

Linux and macOS

To install [Node.js][node] you can use [nvm][nvm]. For example, to install with nvm with [Homebrew][brew], and then install the latest version of Node:

brew install nvm
nvm install node
nvm install-latest-npm

Alternatively, download a pre-built package from the [Node.js][node] website for your operating system.

Windows

On Windows 10, download a pre-built package from the [Node.js][node] website. Pa11y will be usable via the bundled Node.js application as well as the Windows command prompt.

Command-line interface

Install Pa11y globally with [npm][npm]:

npm install -g pa11y

$ pa11y --help

Usage: pa11y [options] <url>

  Options:

    -V, --version                  output the version number
    -n, --environment              output details about the environment Pa11y will run in
    -s, --standard <name>          the accessibility standard to use: WCAG2AAA (only used by htmlcs), WCAG2AA (default), or WCAG2A
    -r, --reporter <reporter>      the reporter to use: cli (default), csv, json
    -e, --runner <runner>          the test runners to use: htmlcs (default), axe
    -l, --level <level>            the level of issue to fail on (exit with code 2): error, warning, notice
    -T, --threshold <number>       permit this number of errors, warnings, or notices, otherwise fail with exit code 2
    -i, --ignore <ignore>          types and codes of issues to ignore, a repeatable value or separated by semi-colons
    --include-notices              include notices in the report
    --include-warnings             include warnings in the report
    --level-cap-when-needs-review <level>   (axe-only) cap severity of any issue requiring manual review to: error (default), warning, notice'
    -R, --root-element <selector>  a CSS selector used to limit which part of a page is tested
    -E, --hide-elements <hide>     a CSS selector to hide elements from testing, selectors can be comma separated
    -c, --config <path>            a JSON or JavaScript config file
    -t, --timeout <ms>             the timeout in milliseconds
    -w, --wait <ms>                the time to wait before running tests in milliseconds
    -d, --debug                    output debug messages
    -S, --screen-capture <path>    a path to save a screen capture of the page to
    -A, --add-rule <rule>          WCAG 2.1 rules to include, a repeatable value or separated by semi-colons – only used by htmlcs runner
    -h, --help                     output usage information

Testing with pa11y

Find accessibility issues at a URL:

pa11y https://example.com

The default test runner is [HTML_CodeSniffer][htmlcs], but [axe] is also supported. To use axe:

pa11y https://example.com --runner axe

Use both axe and HTML_CodeSniffer in the same run:

pa11y https://example.com --runner axe --runner htmlcs

Generate results in CSV format, and output to a file, report.csv:

pa11y https://example.com > report.csv --reporter csv 

Find accessibility issues in a local HTML file (absolute paths only, not relative):

pa11y ./path/to/your/file.html

Exit codes

The command-line tool uses the following exit codes:

• 0: Pa11y ran successfully, and there are no errors
• 1: Pa11y failed run due to a technical fault
• 2: Pa11y ran successfully but there are errors in the page

By default, only accessibility issues with a type of error will exit with a code of 2. This is configurable with the --level flag which can be set to one of the following:

• error: exit with a code of 2 on errors only, exit with a code of 0 on warnings and notices
• warning: exit with a code of 2 on errors and warnings, exit with a code of 0 on notices
• notice: exit with a code of 2 on errors, warnings, and notices
• none: always exit with a code of 0

Command-line configuration

The command-line tool can be configured with a JSON file as well as arguments. By default it will look for a pa11y.json file in the current directory, but you can change this with the --config flag:

pa11y https://example.com --config ./path/to/config.json 

If any configuration is set both in a configuration file and also as a command-line option, the value set in the latter will take priority.

For more information on configuring Pa11y, see the configuration documentation.

Ignoring

The ignore flag can be used in several different ways. Separated by semi-colons:

pa11y https://example.com --ignore "issue-code-1;issue-code-2" 

or by using the flag multiple times:

pa11y https://example.com --ignore issue-code-1 --ignore issue-code-2 

Pa11y can also ignore notices, warnings, and errors up to a threshold number. This might be useful if you're using CI and don't want to break your build. The following example will return exit code 0 on a page with 9 errors, and return exit code 2 on a page with 10 or more errors.

pa11y https://example.com --threshold 10 

Reporters

The command-line tool can provide test results in a few different ways using the --reporter flag. The built-in reporters are:

• cli: output test results in a human-readable format
• csv: output test results as comma-separated values
• html: output test results as an HTML page
• json: output test results as a JSON array
• tsv: output test results as tab-separated values

You can also write and publish your own reporters, which must be CommonJS modules, and may be installed packages or local files. Pa11y checks for reporter modules in a specific order, and the first reporter found will be loaded. So with this command:

pa11y https://example.com --reporter rainbows 

The following locations will be checked, in order:

• An installed package named pa11y-reporter-rainbows
• A module file located at <cwd>/rainbows

For each of these, Pa11y will use the standard Node.js require function to attempt to load the module, so the module must be resolvable by require, and follows the standard CommonJS module resolution order. If no runner is found then Pa11y will error.

A Pa11y reporter must export a string property named supports. This is a [semver range] which indicates which versions of Pa11y the reporter supports:

exports.supports = '^8.0.0';

A reporter should export the following methods, each returning one string. If your reporter needs to perform asynchronous operations, then it may return a promise which resolves to a string:

begin(); // Called when pa11y starts
error(message); // Called when a technical error is reported
debug(message); // Called when a debug message is reported
info(message); // Called when an information message is reported
results(results); // Called with a test run's results

JavaScript interface

Add Pa11y to your project with [npm][npm], most commonly as a development dependency:

npm install pa11y --save-dev

Require Pa11y:

const pa11y = require('pa11y');

Run Pa11y against a URL, the pa11y function returns a [Promise]:

pa11y(url).then((results) => {
    // Use the results
});

Pa11y can also be run with options:

const options = { /* ... */ };
pa11y(url, options)).then((results) => {
    // Use the results
});

Pa11y resolves with a results object, containing details about the page, and an array of accessibility issues found by the test runner:

{
    pageUrl: 'The tested URL',
    documentTitle: 'Title of the page under test',
    issues: [
        {
            code: 'WCAG2AA.Principle1.Guideline1_1.1_1_1.H30.2',
            context: '<a href="https://example.com/"><img src="https://github.com/pa11y/pa11y/raw/9.1.1/example.jpg" alt=""/></a>',
            message: 'Img element is the only content of the link, but is missing alt text. The alt text should describe the purpose of the link.',
            selector: 'html > body > p:nth-child(1) > a',
            type: 'error',
            typeCode: 1
        }
    ]
}

Transforming the results

If you wish to transform these results with a command-line reporter, require it into your code. The csv, tsv, html, json, and markdown reporters each expose a method process:

// Assuming you've already run tests, and the results
// are available in a `results` variable:
const htmlReporter = require('pa11y/lib/reporters/html');
const html = await htmlReporter.results(results);

async/await

Pa11y uses promises, so you can use async functions and the await keyword:

async function runPa11y() {
    try {
        const results = await pa11y(url);
        // Use the results
    }
    catch (error) {
        // Handle error
    }
}

runPa11y();

Callback interface

For those who prefer callbacks to promises:

pa11y(url, (error, results) => {
    // Use results, handle error
});

Validating actions

Pa11y's isValidAction function can be used to validate an action string ahead of its use:

pa11y.isValidAction('click element #submit');  // true
pa11y.isValidAction('open the pod bay doors'); // false

Configuration

Pa11y has lots of options you can use to change the way Headless Chrome runs, or the way your page is loaded. Options can be set either as a parameter on the pa11y function or in a JSON or JavaScript configuration file. Some are also available directly as command-line options.

Below is a reference of all the options that are available. Example JSON and JavaScript configuration files are available in example/configs/. Note that unlike pa11y-ci configuration, there is no defaults property.

actions (array)

Actions to be run before Pa11y tests the page. There are quite a few different actions available in Pa11y, the Actions documentation outlines each of them.

pa11y(url, {
    actions: [
        'set field #username to exampleUser',
        'set field #password to password1234',
        'click element #submit',
        'wait for path to be /myaccount'
    ]
});

Defaults to an empty array.

browser (Browser) and page (Page)

A [Puppeteer Browser instance][puppeteer-browser] which will be used in the test run. Optionally you may also supply a [Puppeteer Page instance][puppeteer-page], but this cannot be used between test runs as event listeners would be bound multiple times.

If either of these options are provided then there are several things you need to consider:

1. Pa11y's chromeLaunchConfig option will be ignored, you'll need to pass this configuration in when you create your Browser instance
2. Pa11y will not automatically close the Browser when the tests have finished running, you will need to do this yourself if you need the Node.js process to exit
3. It's important that you use a version of Puppeteer that meets the range specified in Pa11y's package.json
4. You cannot reuse page instances between multiple test runs, doing so will result in an error. The page option allows you to do things like take screen-shots on a Pa11y failure or execute your own JavaScript before Pa11y

Note: This is an advanced option. If you're using this, please mention in any issues you open on Pa11y and double-check that the Puppeteer version you're using matches Pa11y's.

const browser = await puppeteer.launch({
    ignoreHTTPSErrors: true
});

pa11y(url, {
    browser: browser
});

browser.close();

A more complete example can be found in the puppeteer examples.

Defaults to null.

chromeLaunchConfig (object)

Launch options for the Headless Chrome instance. [See the Puppeteer documentation for more information][puppeteer-launch].

pa11y(url, {
    chromeLaunchConfig: {
        executablePath: '/path/to/Chrome',
        ignoreHTTPSErrors: false
    }
});

Defaults to:

{
    ignoreHTTPSErrors: true
}

headers (object)

A key-value map of request headers to send when testing a web page.

pa11y(url, {
    headers: {
        Cookie: 'foo=bar'
    }
});

Defaults to an empty object.

hideElements (string)

A CSS selector to hide elements from testing, selectors can be comma separated. Elements matching this selector will be hidden from testing by styling them with visibility: hidden.

pa11y(url, {
    hideElements: '.advert, #modal, div[aria-role=presentation]'
});

ignore (array)

An array of result codes and types that you'd like to ignore. You can find the codes for each rule in the console output and the types are error, warning, and notice. Note: warning and notice messages are ignored by default.

pa11y(url, {
    ignore: [
        'WCAG2AA.Principle3.Guideline3_1.3_1_1.H57.2'
    ]
});

Defaults to an empty array.

ignoreUrl (boolean)

Whether to use the provided [Puppeteer Page instance][puppe