pa11y is your automated accessibility testing pal
pa11y is your automated accessibility testing pal. It runs HTML CodeSniffer from the command line for programmatic accessibility reporting.
On the command line:
var pa11y = require'pa11y';var test = pa11yoptions;testrun'nature.com'/* ... */;
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.12) but only after installing Visual Studio and the Windows SDK (as well as Git, Python and PhantomJS). The Windows installation instructions for node-gyp are a good place to start.
Install pa11y globally with npm:
npm install -g pa11y
This installs the
pa11y command-line tool:
Usage: pa11y [options] <url>Options:-h, --help output usage information-V, --version output the version number-s, --standard <name> the accessibility standard to use: Section508, WCAG2A, WCAG2AA (default), WCAG2AAA-r, --reporter <reporter> the reporter to use: cli (default), csv, html, json-l, --level <level> the level of message to fail on (exit with code 2): error, warning, notice-i, --ignore <ignore> types and codes of messages to ignore separated by semi-colons-c, --config <path> a JSON config file-p, --port <port> the port to run PhantomJS on-t, --timeout <ms> the timeout in milliseconds-w, --wait <ms> the time to wait before running tests in milliseconds-d, --debug output debug messages-H, --htmlcs <url/path> the URL or path to source HTML_CodeSniffer from
Run an accessibility test against a URL:
Run a test with CSV reporting and save to a file:
pa11y --reporter csv nature.com > report.csv
Run pa11y with the Section508 ruleset:
pa11y --standard Section508 nature.com
The command-line tool uses the following exit codes:
0: pa11y ran successfully, and there are no errors
1: pa11y failed run due to a technical fault
2: pa11y ran successfully but there are errors in the page
By default, only accessibility issues with a type of
error will exit with a code of
2. This is configurable with the
--level flag which can be set to one of the following:
error: exit with a code of
2on errors only, exit with a code of
0on warnings and notices
warning: exit with a code of
2on errors and warnings, exit with a code of
notice: exit with a code of
2on errors, warnings, and notices
none: always exit with a code of
The command-line tool can be configured with a JSON file as well as arguments. By default it will look for a
pa11y.json file in the current directory, but you can change this with the
pa11y --config ./path/to/config.json nature.com
For more information on configuring pa11y, see the configuration documentation.
The command-line tool can report test results in a few different ways using the
--reporter flag. The built-in reporters are:
cli: output test results in a human-readable format
csv: output test results as comma-separated values
html: output test results as an HTML document
json: output test results as a JSON array
markdown: output test results as a Markdown document
You can also write and publish your own reporters. Pa11y looks for reporters in the core library, your
node_modules folder (with a naming pattern), and the current working directory. The first reporter found will be loaded. So with this command:
pa11y --reporter rainbows nature.com
The following locations will be checked:
A pa11y reporter should export the following methods:
beginurl; // Called when pa11y startserrormessage; // Called when a technical error is reporteddebugmessage; // Called when a debug message is reportedinfomessage; // Called when an information message is reportedresultsresultsArray url; // Called with the results of a test run
You may find the following reporters useful:
1.0-json: output test results in the pa11y 1.0 JSON format
Install pa11y with npm or add to your
npm install pa11y
var pa11y = require'pa11y';
Create a tester by initialising pa11y with some options:
var test = pa11yoptions;
test.run function can then be used to run your test function against a URL:
The results that get passed into your test callback come from HTML CodeSniffer, and look like this:
code: 'WCAG2AA.Principle1.Guideline1_1.1_1_1.H30.2'context: '<a href=""><img src="example.jpg" alt=""/></a>'message: 'Img element is the only content of the link, but is missing alt text. The alt text should describe the purpose of the link.'selector: 'html > body > p:nth-child(1) > a'type: 'error'typeCode: 1code: 'WCAG2AA.Principle1.Guideline1_3.1_3_1.H49.B'context: '<b>Hello World!</b>'message: 'Semantic markup should be used to mark emphasised or special text so that it can be programmatically determined.'selector: '#content > b:nth-child(4)'type: 'warning'typeCode: 2code: 'WCAG2AA.Principle2.Guideline2_4.2_4_4.H77,H78,H79,H80,H81'context: '<a href="">Hello World!</a>'message: 'Check that the link text combined with programmatically determined link context identifies the purpose of the link.'selector: 'html > body > ul > li:nth-child(2) > a'type: 'notice'typeCode: 3
pa11y has lots of options you can use to change the way PhantomJS runs, or the way your page is loaded. Options can be set either on the pa11y instance when it's created or the individual test runs. This allows you to set some defaults which can be overridden per-test:
// Set the default Foo header to "bar"var test = pa11ypage:headers:Foo: 'bar';// Run a test with the Foo header set to "bar"testrun'' /* ... */ ;// Run a test with the Foo header overriddentestrun''page:headers:Foo: 'hello'/* ... */ ;
Below is a reference of all the options that are available:
The path or URL to source HTML CodeSniffer from.
Defaults to a local copy of HTML CodeSniffer, found in lib/vendor/HTMLCS.js.
An array of result codes and types that you'd like to ignore. You can find the codes for each rule in the console output and the types are
Defaults to an empty array.
An object which implements the methods
info which will be used to report errors and test information.
pa11ylog:debug: console.logbindconsoleerror: console.errorbindconsoleinfo: console.infobindconsole;
Each of these defaults to an empty function.
A key-value map of request headers to send when testing a web page.
Defaults to an empty object.
A key-value map of settings to add to the PhantomJS page. For a full list of available settings, see the PhantomJS page settings documentation.
pa11ypage:settings:loadImages: falseuserName: 'nature'password: 'say the magic word';
userAgent: 'pa11y/<version> (truffler/<version>)'
The viewport width and height in pixels. The
viewport object must have both
pa11ypage:viewport:width: 320height: 480;
width: 1024height: 768
A key-value map of settings to initialise PhantomJS with. This is passed directly into the
phantom module – documentation can be found here. You can pass PhantomJS command-line parameters in the
phantom.parameters option as key-value pairs.
pa11yphantom:port: 1234parameters:'ignore-ssl-errors': 'false''ssl-protocol': 'tlsv1';
phantom.port is not specified, a random available port will be used.
The accessibility standard to use when testing pages. This should be one of
The time in milliseconds that a test should be allowed to run before calling back with a timeout error.
The time in milliseconds to wait before running HTML CodeSniffer on the page.
Run pa11y on a URL and output the results:
Use async to run pa11y on multiple URLs in series, and output the results:
Common questions about pa11y are answered here.
page.headers option either in your JS code or in your JSON config file:
page.settings option either in your JS code or in your JSON config file to set a username and password:
pa11ypage:settings:userName: 'nature'password: 'say the magic word';
phantom.parameters option either in your JS code or in your JSON config file:
pa11yphantom:parameters:'proxy': '126.96.36.199:8080''proxy-type': 'http''proxy-auth': 'username:password';
These match PhantomJS command-line parameters.
proxy-type can be set to
To contribute to pa11y, clone this repo locally and commit your code on a separate branch.
Please write unit tests for your code, and check that everything works by running the following before opening a pull-request:
If you're using pa11y 1.0 or 2.0 and wish to migrate to 3.0, we've written a Migration Guide to help with that.
It's recommended that you migrate to 3.0 as soon as possible, but we maintain branches for previous major versions. Each of these will be supported (critical bug fixes only) for 1 year from the next major version's released date:
If you're opening issues related to these, please mention the version being used.
Copyright 2013 Nature Publishing Group.
pa11y is licensed under the GNU General Public License 3.0.