Accessibility Scanning
Accessibility Scanning using AccessLint
AccessLintCI is an automated accessibility scanning tool. It is configured with CircleCI (Travis and Jenkins support pending) to leave comments on Pull Requests stating potential accessibility problems with the committed code.
Getting started
Regardless of what framework your project is using, you will need to add gem: accesslint-ci
to your Gemfile
with the gem.
Setup with Jekyll
The setup is detailed here for Rails, but can also easily be configured with Jekyll sites as follows. In the circle.yml
file of your repo add the following:
general:
artifacts:
- "tmp"
machine:
environment:
ACCESSLINT_MASTER_BRANCH: <Branch that you want accesslint to test against>
node:
version: 6.1.0
dependencies:
pre:
- gem install bundler
- bundle install
override:
- npm install -g accesslint-cli
- gem install accesslint-ci
test:
post:
- bundle exec jekyll serve --detach
- accesslint-ci scan http://localhost:4000
The ACCESSLINT_MASTER_BRANCH
should be set to the branch that PRs are being made to. If it is not set, it will default to master
. For TTS repos, this will generally be dev
or development
.
Accesslint API access
In order for AccessLint to access your GitHub webhooks, you will need to
- Create an token
- Reference it. In your Circle CI settings for your repo, create a variable named
ACCESSLINT_API_TOKEN
with the token you created. - Also add a variable named
ACCESSLINT_GITHUB_USER
to your Circle CI repo settings, with a value of the GitHub username that was used to create the token in step 1.
Configuring other project frameworks
If your project is not a Rails or Jekyll project, you can still use AccessLintCI!
To do so, make a few changes to the post
section of your configuration. Replace bundle exec jekyll serve --detach
with a repo-specific server command that detaches, and allows accesslint-ci to run on the same process to check your server port.
test:
post:
- <your detached server command>
- accesslint-ci scan http://localhost:<your server port>
What it does
Once configured, AccessLintCI will leave a single comment on a Pull Request to the ACCESSLINT_MASTER_BRANCH
. If errors are accepted, they will be cached, and not checked again in the next PR to that branch.
Accessibility Scanning Using Pa11y-ci
Introduction
Building a website or application that is easy accessible toeveryone is not only an important of the user experience, but also a requirement of all federally funded projects. GSA provides a helpful Section 508 portal. Pa11y is an automation tool that helps you scan your static web pages to check for accessibility problems and errors. It can be setup on your machine locally or remotely using a CI tool.
Running Pa11y locally
Installation and setup (For MacOS)
-
Concourse CI allows you to run multiple compliance scanning jobs on your machine using a virtual machine. It is highly recommended to go through its excellent documentation and “Hello World” tutorial before writing custom jobs for your project.
-
If you want to run locally Pa11y-ci you will need to :
- install vagrant and virtualbox
- use The Fly CLI , a command line tool for Concourse which is used for a number of tasks from connecting to a shell in one of your build’s containers to uploading new pipeline configuration into a running Concourse.
-
If you’re on MacOS , you will have to
chmod +x
the downloaded binary and put it in your$PATH
. This can be done in one fell swoop withinstall path/to/fly /usr/local/bin/fly
-
Run Vagrant
vagrant init concourse/lite # creates ./Vagrantfile vagrant up # downloads the box and spins up the VM
-
Log into fly
fly -t lite login -c http://192.168.100.4:8080
Running Pa11y-ci on your local machine
-
Create a
.yml
file containing the job with tasks that you want to runtouch accessibility-scan.yml
vim accessibility-scan.yml
jobs: - name: accessibility-scan plan: - task: run-pa11y config: platform: linux image_resource: type: docker-image source: repository: node run: path: sh args: - -exc - | npm install -g pa11y-ci npm install -g phantomjs mkdir accessibility-scan pa11y-ci --json --sitemap https://18f.gsa.gov/sitemap.xml > accessibility-scan/summary.txt cat accessibility-scan/summary.txt
type
is almost always going to bedocker-image
.pa11y-ci
requires node, so we are using anode
docker-image.run
section contains a series of shell command that we are executing:-
install
pa11y-ci
andphantomjs
from the node package manager(npm
) -
making a directory and telling pa11y-ci to pipe the results of the scan into a
json
filethe command is like so
pa11y-ci --json --sitemap https://[18f-static-site-url]/sitemap.xml > dir/file
-
printing the results in our CLI
cat…
(for debugging purposes, optional)
Note that we are using the
sitemap.xml
file instead of individual files(much more efficient) -
-
Run
fly -t lite set-pipeline -p accessibility-scan -c accessibility-scan.yml
-
Go to the
URL
displayed on your CLI. Click the plus sign on top right corner and toggle side bar and press play on your pipeline. Pipelines are posed by default.
Running Pa11y-ci with CI
Circle CI Setup Instructions
If you want to run Pa11y-ci per pull request on your project:
-
Create a bash file
accessibility-scan.sh
in your project home directory to tell it to run either on a circleci supported branch or your localhostif [[ -n $CIRCLE_BRANCH ]]; then echo "scanning site using sitemap from 18F/${CIRCLE_BRANCH}" pa11y-ci --sitemap https://federalist.18f.gov/preview/18F/18f.gsa.gov/${CIRCLE_BRANCH}/sitemap.xml else echo "scanning site using localhost sitemap" pa11y-ci --sitemap http://localhost:4000/sitemap.xml
-
Modify your
circle.yml
to add pa11y-ci
machine: ruby: version: 2.2.3 dependencies: pre: - [Your-other-commands] - nvm install stable && nvm alias default stable - npm test - npm install -g pa11y-ci test: pre: - bundle exec htmlproofer _site --disable-external --allow-hash-href --empty-alt-ignore --url-ignore 18f@gsa.gov - echo CIRCLE_BRANCH - echo - npm run --harmony accessibility-scan