Accessibility Testing That Actually Fits Into Your Workflow

You know you should be testing for accessibility. You also know that doing it manually, page by page, doesn't scale. So what if you could run those checks the same way you run your other tests—from the terminal, or straight from your Node.js code? That's exactly what Pa11y is built for.

What It Does

Pa11y is an automated accessibility testing tool that runs against your pages via the command line or as a Node.js module. You point it at a URL (or a local HTML file), and it runs accessibility tests and returns results you can act on.

Under the hood, Pa11y supports two test runners: HTML_CodeSniffer (the default) and axe. You can use either one, or run both in the same pass if you want broader coverage. It supports multiple output formats—CLI, CSV, and JSON—so you can read results in your terminal, pipe them into a file, or feed them into whatever tooling you've already got.

It's published on npm, licensed under LGPL-3.0-only, and requires an even-numbered version of Node.js 22.13.0 or above (Pa11y 9 and below will work if you're on an older Node version).

Why It's Cool

• It meets you where you already work. There's no dashboard to log into and no separate service to manage. If you're comfortable in a terminal, you're already comfortable with Pa11y. One command and you've got results.

• The runner flexibility is genuinely useful. HTML_CodeSniffer and axe don't catch exactly the same things. Being able to run --runner axe --runner htmlcs in a single invocation means you don't have to choose one or stitch together two separate tools to get decent coverage.

• Exit codes make it CI-friendly. The --level flag lets you decide what counts as a failure (error, warning, or notice), and the tool exits with code 2 when your threshold is crossed. That's the kind of detail that makes a tool usable in an automated pipeline rather than just a novelty you run by hand.

• The --threshold flag is a nice bit of pragmatism. You can permit a certain number of issues before failing. If you're adopting accessibility testing on a legacy codebase with hundreds of existing problems, this lets you ratchet down gradually instead of blocking every build on day one.

• You can scope the test. The --root-element flag takes a CSS selector to limit which part of a page gets tested, and --hide-elements lets you exclude elements entirely. Useful when you've got a third-party widget you can't fix but don't want polluting your reports.

• Ignoring specific issues is built in. The --ignore flag accepts types and codes you want to skip, as a repeatable value or semicolon-separated list. Sometimes a flagged issue is a false positive or an accepted risk—this keeps your reports honest.

• Config files and JavaScript API. Beyond the CLI flags, you can pass a JSON or JavaScript config file, or use the Node.js API directly if you'd rather wire it into a custom script or test suite.

How to Try It

First, make sure you're on a compatible Node.js version (even-numbered, 22.13.0 or above). Then install it globally:

npm install -g pa11y

Run it against any URL:

pa11y https://example.com

Try the axe runner instead of the default:

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

Or run both runners at once:

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

Want CSV output saved to a file?

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

You can also test a local HTML file (absolute paths only—relative paths won't work):

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

And if you'd rather use it in JavaScript:

const pa11y = require('pa11y');

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

Run pa11y --help to see the full list of options, including standard selection (WCAG2A, WCAG2AA, WCAG2AAA), timeouts, wait times, screen capture, and debug output.

You can find the project at github.com/pa11y/pa11y.

Final Thoughts

Pa11y isn't trying to be everything. It's a focused tool that does one job—automated accessibility testing—and it does it in a way that slots into existing workflows rather than demanding new ones. The exit codes, thresholds, and ignore rules suggest it was designed by people who've actually tried to introduce accessibility testing to a real project and hit the friction points.

If you're a developer who wants to start catching accessibility issues without a big process change, this is a sensible place to start. And if you're already running it, the dual-runner support is worth revisiting—chances are there's something axe catches that HTML_CodeSniffer misses, or vice versa.

Follow @githubprojects for more developer tools and open source projects.