pa11y Accessibility Testing With Docker and Jenkins

pa11y Accessibility Testing With Docker and Jenkins

Testing a website for accessibility might prove challenging. Fortunately with the advent of some opensource tools, it’s easier to test for problems, but automating this is a challenge. In this article we’ll explore how to setup a Jenkins pipeline that runs pa11y - a popular opensource accessibility checker - inside a docker container.

TL;DR: The whole pipeline project, including config, and Dockerfile is available here just to import in Jenkins and run: https://github.com/bmustiata/pa11y-jenkins

1. Creating a Docker Image that can run pa11y

FROM node:8                                           (1)
RUN npm install -g pa11y --unsafe-perm=true           (2)
RUN apt update -y && \
    apt install -y gconf-service [...] wget
COPY /pa11y.config.json /pa11y.config.json            (3)

1. We start from node, and install pa11y.

2. Unfortunately the bundled bundled phantomjs can’t magically fetch its binary dependencies it needs, so we install them as a separate step. There’s a bunch of them, so I snipped this listing.

3. Last, we create a configuration that allows us running chrome without sandboxing - since we’re going to be sandboxed by Docker anyway as an unprivileged container. Also without shared memory support, since unless the container is instantiated with it, it won’t work:

{
    "allowedStandards": "WCAG2AA",
    "level": "error",
    "chromeLaunchConfig": {
        "args": [
            "--no-sandbox",
            "--disable-setuid-sandbox",
            "--disable-dev-shm-usage"
        ]
    }
}

We also added the standard to test, and when to fail the pa11y command. pa11y also supports thresholds, and different standards to evaluate.

2. Wiring it up in Jenkins

We continue by creating the pipeline. This is straightforward, since the heavy lifting of docker is done. We only parametrize the URL to test as SITE_URL:

properties([
    parameters([
        string(name: 'SITE_URL', defaultValue: 'http://germaniumhq.com/',
                description: 'URL to test the accesibility against')
    ])
])

SITE_URL = params.SITE_URL ?: 'http://germaniumhq.com/'

stage('Test URL') {
    node {
        deleteDir()
        checkout scm

        docker.build('germaniumhq/pa11y')
            .inside {
            sh """
                pa11y -c /pa11y.config.json "${SITE_URL}"
            """
        }
    }
}

Sweet! Note that we’re passing the configuration parameter in (/pa11y.config.json)

We are done. This project is now ready to be imported into the Jenkins installation and ran.

Happy testing!

Article Photo from Pexels: https://www.pexels.com/photo/different-choices-of-eyeglasses-1627639/