< Using Pa11y with Jekyll and CircleCI

To start with, Pa11y is an open source accessibility checker. It is one of the first tools I use to do accessibility audits, and did I mention it’s open source? See Rowan’s post on Pa11y. I love using Pa11y, it is so useful and informative on accessibility issues that I could fix on projects.

As part of my work at the Financial Times, I work on a sizable number of front end modules. One of those includes Origami’s website. The team wanted to integrate Pa11y with CircleCI into the website. One notable difference is that Pa11y uses Travis CI on their own website, whereas Origami uses CircleCI. The configs for Travis and CircleCI are different.

Travis

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Run with Node.js 4
language: node_js
node_js:
- '4'

# Restrict builds on master branch
branches:
only:
- master

# Installation
before_install:
- rvm install 2.2.2
install:
- make install

# Build script
script:
- make serve &
- sleep 5
- make test

The original Pa11y .travis.yml code can be seen on GitHub.

What this does is installs Node.js 4, Ruby, the Pa11y npm module and the GitHub Pages gem and runs tests. The first test is to do jekyll serve --watch in the background, then it waits 5 seconds before doing a test. If you are wondering what make install, make serve or make test does then, this should answer your questions (This is Origami’s version).

CircleCI

I wanted to replicate the above config with CircleCI’s own circle.yml. The configs are quite different, and the & directive does not work with CircleCI. From looking at CircleCI’s documentation on background process. I came to the conclusion that I would need to do the following:

1
2
3
4
5
6
test:
override:
- make serve:
background: true
- sleep 5
- make test

And then this would replicate the original tests that the .travis.yml on Pa11y does (Note the : on make serve to set it as a background process) I have now made a working CircleCI config that will work with Pa11y and Jekyll.

Full CircleCI config

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
machine:
node:
version: 4
ruby:
version: 2.3.0
dependencies:
pre:
- make install
cache_directories:
- "node_modules"
test:
override:
- make serve:
background: true
- sleep 5
- make test

The circle.yml file is at Financial-Times/ft-origami on GitHub.

Conclusion

From two different CI processes, with different configuration options. This was an interesting problem to fix. I had one test build where it was running the jekyll serve --watch without it being in the background. I did wonder why it was running so long until I realised it needed to be a background process. That brought out a chuckle.

I hope this post was informative if you wanted to use CircleCI alongside Pa11y and Jekyll on a website.