pa11y
pa11y is your automated accessibility testing pal.
It runs HTML CodeSniffer from the command line for programmatic accessibility reporting.
Current Version: 1.1.0
Node Version Support: 0.10
Installing
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
Usage
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
-t, --timeout <ms> specify the number of milliseconds before a timeout error occurs. Default: 30000
-d, --debug output debug messages
Example:
$ pa11y nature.com
$ pa11y -r csv nature.com > report.csv
$ pa11y -s WCAG2AAA nature.com
Caveats
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!
Custom Reporters
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()
exports.log(str)
exports.debug(str)
exports.error(str)
exports.handleResult(results)
exports.end()
For example reporters, take a look at the built-in reporters or the rainbows reporter.
Development
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
$ make lint
$ make test
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.
License
Copyright 2013 Nature Publishing Group.
pa11y is licensed under the GNU General Public License 3.0.