Accessibility testing, with 'pa11y-ci'

I’ve recently come across an open source, automated accessibility testing tool called pa11y-ci, and I’m really impressed with how easy it is to set up, and the usefulness of the results.

Note, tools like pa11y-ci are not of course a replacement for accessibility testing with humans.

pa11y-ci is written in Javascript for Node.js. It is built on top of pa11y, and HTML_CodeSniffer. And, it integrates well with continuous integration platforms like Travis-CI.

Here’s a run down on how I’m using it so far. (You’ll need npm.)

To get started, run this command in your terminal:

npm install pa11y-ci --save-dev

Create a configuration file named .pa11yci.json, specifying a standard, some urls and other options. Here’s an example:

  "#": "Automated accessibility testing ~",

  "defaults": {
    "standard": "WCAG2AAA",
    "timeout": 5000,
    "wait": 2000,
    "verifyPage": "gaad-widget-js"
  "urls": [

I’m eschewing Grunt et al, and simply adding scripts to my package.json:

  "devDependencies": {
    "pa11y-ci": "^1.3.1"
  "scripts": {
    "pa11y-ci": "pa11y-ci --config .pa11yci.json"

To run the above script, type this in your terminal:

npm run pa11y-ci

Here’s a more complete package.json:

  "name": "gaad-widget",

  "devDependencies": {
    "live-server": "^1.2.0",

    "pa11y-ci": "^1.3.1"
  "scripts": {
    "test": "echo Testing ...",
    "serve-ci": "live-server --port=9001 -V --no-browser --watch=DUMMY",

    "pa11y": "pa11y --standard WCAG2AAA",
    "pa11y-ci": "pa11y-ci --config .pa11yci.json"

And, here is a simplified .travis.yml file:

language: node_js

node_js: 8

  depth: 8

install: npm install

before_script: npm run build

  - npm test
  - npm run serve-ci & sleep 5; npm run pa11y-ci;

The above results in this Travis-CI job output:

> pa11y-ci --config .pa11yci.json
Running Pa11y on 2 URLs:
GET /embed/?gaadwidget=force&_ua=pa11y-ci 200 28.105 ms - 1708
GET /test/static.html?_ua=pa11y-ci 200 30.170 ms - 1792
GET /dist/gaad-widget.js 200 4.013 ms - 12631
GET /style/gaad-widget.css 200 3.276 ms - 1125
 > - 0 errors
 > - 0 errors
✔ 2/2 URLs passed

The good:

The bad:

If you’d like to use pa11y-ci, why not add a badge to your README? For example:

Accessibility testing - GAAD passes

Articles by Andrew Mee, Ire Aderinokun and others contain more useful tips.

Loading comments ...