jryanconklin/pa11y-dashboard

A migration repo for pa11y dashboard

pa11y dashboard

A Vue.js powered display of accessibility results generated by pa11y or 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).

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 --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 the pa11y result dashboard
  # docker-compose run --rm dashboard
  dashboard:
    image: theffner/vue-pa11y
    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.

Local Build Setup

# install pa11y-ci for local use [skip if using docker]
npm install --save pa11y-ci

# install dependencies
npm install

# generate pa11y report [skip if using docker]
npm run report

# serve with hot reload at 0.0.0.0:8080
npm run dev

# build for production with minification
npm run build

# build for production and view the bundle analyzer report
npm run build --report

How to use

With Docker [preferred]

1. Fill out an array of URLs inside of ./tests/pa11y/.pa11yci and any configuration options you need. If you use a different directory than this on your project, be sure to update the volume mounts accordingly.
2. Run docker-compose run pa11y
3. Run docker-compose run dashboard and visit www.pa11y.vm:8080/
4. Re-run docker-compose run pa11y when you need to re-test after making changes.

Locally

0. Install pa11y-ci as a project dependency (npm install --save pa11y-ci)
1. Fill out an array of URLs inside of ./tests/pa11y/.pa11yci and any configuration options you need.
2. Run npm run report to generate the .json file used by the dashboard.
3. npm run dev to see results locally at 0.0.0.0:8080/

For a detailed explanation on how things work under the hood, check out the guide and docs for vue-loader.

pa11y-ci

Configuration options are set in ./tests/pa11y/.pa11yci. See pa11y-ci for more information on specific options. At the very least, a list of urls to test on is needed.

{
  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.