pa11y

Runs automated accessibility tests on your pages via the command line or No...

TestingAccessibilityBrowser automation
pa11y/pa11ypa11y.orgpa11y

README

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.

On the command line:

  1. ```sh
  2. pa11y https://example.com
  3. ```

In JavaScript:

  1. ```js
  2. const pa11y = require('pa11y');

  4. pa11y('https://example.com').then((results) => {
  5.     // Use the results
  6. });
  7. ```

Requirements


Pa11y 7 requires [Node.js][node] 18 or 20 to run. An older version of Node.js can be used with a previous major version of Pa11y.

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:

  1. ```sh
  2. brew install nvm
  3. nvm install node
  4. nvm install-latest-npm
  5. ```

Alternatively, you can also download pre-built packages 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]:

  1. ```sh
  2. npm install -g pa11y
  3. ```

This installs the pa11y command-line tool:

  1. ```sh
  2. Usage: pa11y [options] <url>

  4.   Options:

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

Testing with pa11y


Find accessibility issues at a URL:

  1. ```sh
  2. pa11y https://example.com
  3. ```

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

  1. ```sh
  2. pa11y https://example.com --runner axe
  3. ```

Use both axe and HTML_CodeSniffer in the same run:

  1. ```sh
  2. pa11y https://example.com --runner axe --runner htmlcs
  3. ```

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

  1. ```sh
  2. pa11y https://example.com > report.csv --reporter csv
  3. ```

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

  1. ```sh
  2. pa11y ./path/to/your/file.html
  3. ```