1. Web Design
  2. Web Accessibility

How to Use Pa11y: Web Accessibility Testing Via the Command Line

Read Time:6 minsLanguages:

The world is at a point where it is imperative to design for everyone, and the web is an important part of that. As such, developers and designers need to ensure that their web applications and web pages are accessible to all. 

Getting started with this can be confusing, especially if you are learning about accessibility for the first time. This opinion piece by Sami Keijonen is a great primer:

Moving on from that, a tool that highlights accessibility improvements is a vital thing to add to your web development workflow.

Introducing Pa11y

Pa11y provide a set of free and open-sourced tools to help developers and designers build accessible web pages. 

pa11y logopa11y logopa11y logo

In this tutorial, we will be looking at Pa11y and Pa11y-ci, both command line accessibility tools. If you’d prefer to use a web interface check out Pa11y Dashboard (aka Koa11y).


So what is the Pa11y command line tool? According to the documentation;

“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.”

How to Install and Run Pa11y

You can start by installing the package as a global NPM package. Open your terminal and enter:

To run Pa11y enter the following command (I’m using my own website to demonstrate this first step as it doesn’t throw any accessibility issues): 

An alternative way to install Pa11y involves making use of npx, an npm package runner. In this case run Pa11y as follows:

Pa11y runs accessibility tests on the web pages and returns the results to us. If your website contains no errors you should see a prompt that’s similar to this:

Choosing What to Test For

Now, substitute with, run Pa11y and you will see a list of errors:

The errors you receive might seem overwhelming, but it is possible to be selective about the kind of feedback we want from Pa11y.

How to Select What Kinds of Tests to Run

Pa11y by default sorts the result of the tests into three categories. In the order of least to most critical, these are;

  1. Notice: This informs you about the accessibility of elements on your web page. These are usually non-critical–as such, you can choose to ignore them.
  2. Warning: Pa11y uses this to bring to your attention something that is well worth looking into–accessibility issues that require attention, but aren’t highly critical.
  3. Error: These are critical issues that should be looked into and fixed.

Error messages are the most important, as you can see from the image we have above. If you want to focus on the error messages, you can do so by ignoring the warnings and notices using this command:

This command will now only display error messages. But if that’s possible, can we also ignore error messages? Yes, we can!

This command, as you might imagine, will return non-error messages.

Changing Other Aspects of A11y Reporting

We can also change the accessibility standard we want to use to test for accessibility. This is possible by using the --standard flag.

Using the --reporter flag, you can configure how the messages should be displayed. For example, you can have the messages displayed in JSON format on your terminal.

The output, when shown in the terminal window is not particularly readable. A better solution would be to put the JSON response in a file that you can open in your code editor or IDE. You can do that using the command below:

The json option passed to the --reporter flag overrides the default reporter option (which is the CLI). Then by indicating > errors.json, we tell Pa11y to save the output to an errors.json file. You do not need to have this file created before running the command; the file will be created on the fly and the results will be stored in it.

There is also a CSV reporter available for use.

And you can have the errors stored in a specified CSV file.


Time for tool number two. As the name suggests, Pa11y-CI comes in handy when working with continuous integration. Built with Pa11y, it runs accessibility tests against multiple URLs, ensuring that no accessibility errors make it to production. 

Having gone through the basics of using Pa11y in the above section, Pa11y-CI is what you will want to use in your next big project after getting acquainted with accessibility.

How to Install and Configure Pa11y-CI

Start by installing the package globally on your machine through npm.

Pa11y-CI looks for a JSON configuration file called .pa11yci in the current working directory. There is a --config flag you can use to specify a configuration file in a different directory.

Here is a sample configuration file from the documentation.

Navigate to a clean directory using your terminal, or create a new one. I called my pa11y-test. Create a file called .pa11yci in this new directory. For now, let’s start with this configuration to test multiple URLs.

You should see errors on your terminal, the errors will be for the URLs you indicated.

In the initial configuration we got from the documentation, we had a default object. This object made it possible to specify the configuration that will be used across the URLs we want to test.

For example, we can also define an accessibility standard that will be used as default for the URLs we want to test.

This will override the default standard that Pa11y uses. The configuration above also includes the viewport dimensions we want to use in testing the page.

We can also specify a configuration for a specific URL. For example, after specifying the default accessibility standard we want to make use of (WCAG2AAA), we can override that for one of the URLs we are testing (WCAG2A).

Pa11y-CI also makes it possible to test for user actions, these actions are specifically ones that a user will undergo while navigating your website. For example, we can test the action of when a user clicks the Subscribe with Envato Elements on, that the user is directed to

Wrapping Up

Pa11y-CI shines brighter when used in continuous integration, as the documentation outrightly stated,

“...can act as a gatekeeper to stop a11y issues from making it to live.”

After going through all these and working out the workflow you prefer, I suggest you remain consistent in using it, so as to have a better grasp of what is offered. If there are other web accessibility test tools you use, I’d love to read about them in the comments section!

Learn More About Accessibility Testing

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.