Skip to content

Pa11y

Pa11y opens a page and runs automated accessibility checks from the command line. It can save results in a format your team can compare between runs.

Visit Pa11y

What do you need to run Pa11y?

Pa11y is a free, open-source command-line tool. Its current version 10 requires an even-numbered Node.js version starting at 22.13.0. It opens a browser page and applies an automated rule set.

The default rule set is HTML CodeSniffer. You can choose axe instead. Pa11y CI is a separate companion for a list of pages, and Pa11y Dashboard is another separate project.

How do you compare runs without hiding a new issue?

Save the report as CSV for a spreadsheet or JSON for a program. Keep the tested page, selected rule set and version with it. Check which findings the run is set to report and when it is set to fail.

A threshold can allow some reported problems without failing the build. Agree on what to review so an allowed count does not hide a different issue. Keep reports with sample data and inspect any page details before sharing them.

How can you check that a scan catches a change?

Prepare two standalone sample pages for the same fictional task. Keep sign-in, storage and outgoing connections out of them. If you cannot run Pa11y locally, write the expected result for each and leave the scan untested.

  1. Keep the settings the same
    On the first page, give an Email field its visible label and connect the label to the field. On the second page, remove the label and any other name for that field.
  2. Look for the field result
    Run the same rule set for both pages. Expect a finding about the unnamed field on the second page. Check the field named in the result and keep both reports.
  3. Keep a separate manual pass
    Use the keyboard to reach and edit the field. Check with a screen reader that the label tells someone what to enter.