Pa11y is an automated accessibility testing tool that helps developers ensure their web applications meet accessibility standards. It can be used to run accessibility tests on web pages and generate reports on any issues found.
Run Accessibility Tests
This feature allows you to run accessibility tests on a given URL. The results will include any accessibility issues found on the page.
const pa11y = require('pa11y');
(async () => {
const results = await pa11y('https://example.com');
console.log(results);
})();Custom Configuration
Pa11y allows you to customize the accessibility tests by specifying standards (like WCAG2AA) and other options such as taking a screenshot of the page.
const pa11y = require('pa11y');
(async () => {
const results = await pa11y('https://example.com', {
standard: 'WCAG2AA',
screenCapture: './screenshot.png'
});
console.log(results);
})();Programmatic API
You can use Pa11y's programmatic API to perform actions on the page before running the accessibility tests. This is useful for testing dynamic content.
const pa11y = require('pa11y');
(async () => {
const results = await pa11y('https://example.com', {
actions: [
'click element #button',
'wait for element #result to be visible'
]
});
console.log(results);
})();Axe-core is a popular accessibility testing engine for websites and other HTML-based user interfaces. It provides a comprehensive set of rules for accessibility testing and can be integrated into various testing frameworks. Compared to Pa11y, axe-core is more focused on providing a robust rule set and is often used as a library within other tools.
Accessibility Insights for Web is a tool that helps developers find and fix accessibility issues in web applications. It provides a browser extension and a CLI for automated testing. Compared to Pa11y, Accessibility Insights offers a more user-friendly interface and additional guidance on fixing issues.
Cypress-axe is a plugin for the Cypress end-to-end testing framework that integrates axe-core for accessibility testing. It allows you to run accessibility checks as part of your Cypress test suite. Compared to Pa11y, cypress-axe is more suitable for developers already using Cypress for their testing needs.
pa11y is your automated accessibility testing pal.
It runs HTML CodeSniffer from the command line for programmatic accessibility reporting.
Current Version: 1.4.0
Node Version Support: 0.10
pa11y requires Node.js 0.10+ and PhantomJS.
On a Mac, you can install these with Homebrew:
$ brew install node
$ brew install phantomjs
If you're on Linux, you'll probably be able to work it out.
Windows users approach with caution – we've been able to get pa11y running (Windows 7, Node 0.10) but only after installing Visual Studio and the Windows SDK (as well as Git, Python and PhantomJS).
Once you've got these dependencies, you can install pa11y globally with:
$ npm install -g pa11y
Once installed, the pa11y command should be available to you.
Usage: pa11y [options] <url>
Options:
-h, --help output usage information
-V, --version output the version number
-r, --reporter <name> specify a reporter to use, one of: console (default), csv, json
-s, --standard <name> specify a standard to use, one of: Section508, WCAG2A, WCAG2AA (default), WCAG2AAA
-c, --htmlcs <url> specify a URL to source HTML_CodeSniffer from. Default: squizlabs.github.io
-C, --config <file> specify a JSON config file for ignoring rules
-t, --timeout <ms> specify the number of milliseconds before a timeout error occurs. Default: 30000
-u, --useragent <ua> specify a useragent to use when loading your URL. Default: pa11y/<version>
-p, --port <port> specify the port to run the PhantomJS server on. Default: 12300
-d, --debug output debug messages
# Run pa11y with console reporting
$ pa11y nature.com
# Run pa11y with CSV reporting and save to file
$ pa11y -r csv nature.com > report.csv
# Run pa11y with the WCAG2AAA ruleset
$ pa11y -s WCAG2AAA nature.com
You can also use pa11y from JavaScript by requiring the module directly. This will give you access to the pa11y.sniff function. The sniff function accepts two arguments, the first is an options object, the second is a callback:
var pa11y = require('pa11y');
pa11y.sniff(options, callback);
(string) The URL to sniff. Required.
(string,object) The reporter to use. This can be a string (see command-line usage) or an object (see custom reporters). Default null.
(string) The standard to use. One of Section508, WCAG2A, WCAG2AA, WCAG2AAA. Default WCAG2AA.
(string) The URL to source HTML_CodeSniffer from. Default http://squizlabs.github.io/HTML_CodeSniffer/build/HTMLCS.js.
(string,object) The path to a JSON config file or a config object (see configuration). Default null.
(number) The number of milliseconds before a timeout error occurs. Default 30000.
(string) The user-agent to send with the request. Default pa11y/<version>.
(number) The port the PhantomJS server should run on. Default 12300.
(boolean) Whether to report debug-level messages. Default: false.
The callback function should accept two arguments. The first is an error object or null, the second is an object containing the results of the sniff.
// Sniff a URL
pa11y.sniff({
url: 'nature.com'
}, function (err, results) {
console.log(results); // output results object to console
});
// Sniff a URL, specifying some options
pa11y.sniff({
url: 'nature.com',
standard: 'WCAG2AAA',
timeout: 20000
}, function (err, results) {
console.log(results); // output results object to console
});
// Sniff a nonexistent URL
pa11y.sniff({
url: '$$$'
}, function (err, results) {
console.log(err); // Error: URL could not be loaded
});
pa11y can be configured via a JSON file or JavaScript object, which allows you to specify rules that should be ignored in the report.
On the command line, specify a JSON configuration file with the --config flag:
$ pa11y --config ./config/pa11y.json nature.com
If you're using the JavaScript API, you can pass configurations in by either specifying a JSON file or passing in a config object directly:
pa11y.sniff({
config: __dirname + '/config/pa11y.json'
});
pa11y.sniff({
config: {}
});
The config file or object should be formatted like this, where each of the items in the ignore array is the identifier of a rule you'd like to ignore:
{
"ignore": [
"WCAG2AA.Principle2.Guideline2_4.2_4_2.H25.2",
"WCAG2AA.Principle3.Guideline3_1.3_1_1.H57.2"
]
}
You can find the codes for each rule in the console output, so you can simply copy/paste these into your config. We also maintain a list of all available rules.
pa11y can't catch all accessibility errors. It'll catch many of them, but you should do manual checking as well.
Also, due to HTML CodeSniffer being a graphical tool which highlights elements in the DOM, pa11y is most useful to use as a rough benchmark of how many errors/warnings your site has. The messages themselves don't hold much value outside of the browser yet. We're working on this, and if you have any suggestions then we'd be happy to chat!
Writing your own reporter for pa11y is easy, and will allow you to customise the output. This can be useful for integrating with your CI, producing human-readable reports, graphing, etc.
When a reporter is specified, the program will look for node modules with the name pa11y-reporter-<name>. So if you use the following option:
$ pa11y -r rainbows nature.com
then pa11y will attempt to load the module pa11y-reporter-rainbows.
Reporter modules export the following functions, which will be used by pa11y when that reporter is selected. All functions are optional, but you'll need to implement at least error and handleResult for the reporter to be functional.
exports.begin() // Called before processing, used to output welcome messages or similar
exports.log(str) // Called with logging information
exports.debug(str) // Called with debug information if pa11y is run with the `-d` debug flag
exports.error(str) // Called with error information
exports.handleResult(results) // Called when results are available
exports.end() // Called once everything is done, just before the process exits
For example reporters, take a look at the built-in reporters or the rainbows reporter.
To develop pa11y, you'll need to clone the repo and install dependencies with make deps. If you're on Windows, you'll also need to install Make for Windows.
Once you're set up, you can run the following commands:
$ make deps # Install dependencies
$ make lint # Run JSHint with the correct config
$ make test # Run tests
When no build target is specified, make will run deps lint test. This means you can use the following command for brevity:
$ make
Code with lint errors or failing tests will not be accepted, please use the build tools outlined above.
For users with push-access, don't commit to the master branch. Code should be in develop until it's ready to be released.
Copyright 2013 Nature Publishing Group.
pa11y is licensed under the GNU General Public License 3.0.
FAQs
Pa11y is your automated accessibility testing pal
The npm package pa11y receives a total of 125,075 weekly downloads. As such, pa11y popularity was classified as popular.
We found that pa11y demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 9 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.