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.
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).
Pa11y
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:
npm install -g pa11y
To run Pa11y enter the following command (I’m using my own website https://jioke.me to demonstrate this first step as it doesn’t throw any accessibility issues):
pa11y https://jioke.me
An alternative way to install Pa11y involves making use of npx, an npm package runner. In this case run Pa11y as follows:
npx pa11y https://jioke.me
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:
Welcome to Pa11y > Running Pa11y on URL https://jioke.me No issues found!
Choosing What to Test For
Now, substitute https://jioke.me with https://tutsplus.com, 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;
- 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.
- 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.
- 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:
pa11y --ignore "notice;warning" https://tutsplus.com
This command will now only display error messages. But if that’s possible, can we also ignore error messages? Yes, we can!
pa11y --ignore "error" https://tutsplus.com
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.
pa11y --standard WCAG2AAA https://tutsplus.com
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.
pa11y --reporter json https://tutsplus.com
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:
pa11y --reporter json https://tutsplus.com > errors.json
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.
pa11y --reporter csv https://tutsplus.com
And you can have the errors stored in a specified CSV file.
pa11y --reporter csv https://tutsplus.com > errors.csv
Pa11y-CI
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.
npm install -g pa11y-ci
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.
{
"default": {
"timeout": 1000,
"page": {
"viewport": {
"width": 320,
"height": 480
}
}
},
"urls": [
"https://pa11y.org/",
"http://pa11y.org/contributing"
]
}
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.
{
"urls": [
"http://tutsplus.com/",
"https://tutsplus.com/authors/kingsley-chijioke"
]
}
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.
"defaults": {
"standard": "WCAG2AAA",
"timeout": 1000,
"page": {
"viewport": {
"width": 320,
"height": 480
}
},
"urls": [
"https://tutsplus.com",
"https://tutsplus.com/authors/kingsley-chijioke"
]
}
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).
"defaults": {
"standard": "WCAG2AAA",
"timeout": 1000,
"page": {
"viewport": {
"width": 320,
"height": 480
}
},
"urls": [
{
"url": "http://tutsplus.com/",
"standard": "WCAG2A"
},
"https://tutsplus.com/authors/kingsley-chijioke"
]
}
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 https://tutsplus.com/, that the user is directed to https://tutsplus.com/subscribe-with-elements.
{
"urls": [
{
"url": "https://tutsplus.com",
"actions": [
"click element .home-hero__cta-button",
"wait for url to be https://tutsplus.com/subscribe-with-elements"
]
}
]
}
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
AccessibilityHow to Use the Contrast Checker in Chrome DevTools
Firefox14 Firefox Developer Tools You Might Not Know About
AccessibilityHow We Test for Accessibility at Envato (Tools and Tips)
No comments:
Post a Comment