Accessibility enhances the user experience for everyone, allowing a wider audience to engage with your content. One powerful tool that can help you in this process is Pa11y—a robust, open-source accessibility testing tool that streamlines the identification and resolution of accessibility issues.
In this step-by-step tutorial, I will guide you through the process of setting up and using Pa11y to audit your website’s accessibility. This guide will provide you with the knowledge and tools to make your website more inclusive.
Prerequisites
NodeJS v18 or above
Getting started with pa11y
Pa11y is a command-line interface which loads web pages and highlights any accessibility issues it finds.
Useful for when you want to run a one-off test against a web page.
Installation
pa11y is an npm package, therefore you can simply install it globally on your computer by running in the CLI the following command:
npm install -g pa11y
Testing with pa11y
Find accessibility issues at an URL, running from CLI:
pa11y https://razvanvancea.ro/
Runners: HTML_CodeSniffer vs. axe
Pa11y’s default runner is HTML_CodeSniffer but axe is also supported
Running pa11y with axe:
pa11y https://razvanvancea.ro/ --runner axe
Results
How to display only critical errors
- notice – general message, not necessarily something wrong but to be aware of concerning a particular elemen
- warning – something that we should take a look at it, but not necessarily an error
- error – crucial issue that should be fixed
pa11y https://razvanvancea.ro/ --ignore "warning;notice"
How to hide elements
This approach is used to exclude specific elements from testing (e.g. elements that are visual or screen-reader only)
pa11y https://razvanvancea.ro/ --hide-elements "h1.home__title"
How to set thresholds
These represents the maximum number of accepted errors in order for the test to ‘pass’ or ‘fail’
pa11y https://razvanvancea.ro/ --threshold 5
How to set specific standard (e.g. WCAG2AAA)
Note: if you don’t specify any, WCAG2AA will be used by default
pa11y --standard WCAG2AAA https://razvanvancea.ro/
Test results in a HTML format
pa11y --reporter html https://razvanvancea.ro/ > results.html
Example
Test results in a JSON format
pa11y --reporter json https://razvanvancea.ro/ > results.json
Test results in a CSV format
pa11y --reporter csv https://razvanvancea.ro/ > results.csv
Enjoyed this article? Make sure to subscribe to my YouTube Channel for more Test Automation tutorials, and follow me on LinkedIn and Twitter for regular insights.
Looking to improve your test automation skills?
I’ve created a personalized 1-on-1 Mentoring program refined to boost YOUR skills. Reach out at iamrv@razvanvancea.ro for more details and together will create a learning path adapted to your current skills and goals that you are aiming for, in a timely-efficient manner🚀
I recommend DoesQA if anyone wants to integrate Pa11y into their functional tests. You might need to run the checks on logged-in pages or want accessibility audits after CI/CD or scheduled.