NOTE This repo originally spawned as a proof of concept. Continued work and support can be found here.

pa11y Results Dashboard

A Vue.js powered display of accessibility results generated by pa11y-ci.

This is intended to be used as a docker service, in conjunction with another service that generates reports, but can be run standalone locally if you also install pa11y-ci (npm install --save pa11y-ci). This is not included by default due to pa11y's dependence on a 90mb copy of headless chrome (used to actually run the tests).

Quickstart

This assumes you have access to npm and docker.

1. npm install
2. npm run report
3. docker-compse run --rm pa11y
4. npm run serve

This will install necessary dependencies, convert config to a usuable .json file, run pa11y-ci in a docker container, and then start a webpack dev server locally to see the results in a manageable dashboard.

Generic Docker Usage

Add these to the appropriate docker-compose for your project, and get accessible today!

version: '3.3'
services:

  # a service to generate pa11y results
  # docker-compose run --rm pa11y
  pa11y:
    image: outrigger/pa11y:dev
    container_name: pa11y
    command: bash -c "cd /code/pa11y && pa11y-ci --config /code/pa11y/config.json --json > report.json"
    volumes:
      # pa11y-ci works by default with a .pa11yci file
      - ./tests/pa11y/:/code/pa11y/
    cap_add:
      - SYS_ADMIN

  # a service to spin up this pa11y result dashboard
  # docker-compose run --rm dashboard
  dashboard:
    image: outrigger/pa11y-dashboard
    container_name: pa11ydash
    network_mode: bridge
    environment:
      DNSDOCK_NAME: www
      DNSDOCK_IMAGE: pa11y
    volumes:
      - type: bind
        source: ./tests
        target: /app/tests

The first service uses an image that contains both pa11y and pa11y-ci. It looks for your pa11y config inside of tests/pa11y/, and uses that inside the image. The command switches to the appropriate folder and runs the test based on your config, and outputs results as a JSon object.

The second service runs this dashboard in dev mode, and makes it available outside of the container at www.pa11y.vm/. It looks at ./tests/pa11y/ to ingest the generated report.json from the first service. By running in dev mode, the service can be run once, and will automatically update every time the pa11y service is re-run.

Usage with Docksal

To use this dashboard locally with Docksal, copy the .docksal pa11y command and service definition (both found in the .docksal folder)to your project.

Then, you can run fin pa11y to generate a report. Run fin project up to bring all of your project's containers up, including the pa11y dashboard. It should then be visible at http://pa11y.project.docksal/.

pa11y-ci

Configuration options are set in ./tests/pa11y/.pa11yci.js. See pa11y-ci for more information on specific options. At the very least, a list of urls to test on is needed. This .js file will get converted to a config.json, which is consumed by the docker container that actually runs pa11y-ci.

{
  urls: [
    "http://example.com",
    "http://www.another-example.com",
    "http://a.third.link.io/to/test"
  ]
}

If your site has a sitemap, that can be passed in as an option in the package.json report command, e.g. pa11y-ci --sitemap http://example.com/sitemap.xml -j > pa11y-report.json. This will check the urls in your sitemap, in addition to any links defined inside the .pa11yci urls array noted above.