How I set up a11y testing on this blog

In order to learn more about accessiblity testing, I decided to set up Cypress testing with axe-core on this website. Setting this up was straight-forward and doesn't require too much overhead. I admit that cypress-axe cannot test every accessibility detail, for example focus management. However, with my static site, which at time of writing only has some blogposts, using cypress-axe's cy.checkA11y() has already helped me find hard to notice issues such as heading order.

The tools at play

Setting it up

To avoid copy-pasting documentation which might change, I suggest you follow the documented installation steps for Cypress and then for cypress-axe.

After installing, you will need to add the below line to cypress/support/index.js

import 'cypress-axe'

This hooks injectAxe() and checkA11y() to the cy object, so that you can call those functions in your tests.

Writing your test

Once installed, you can run the following functions in your test

cy.visit('/') // or localhost:<portnumber> or whatever path you want to test
cy.injectAxe() // injects axe-core so that audit can be run on page under test
cy.checkA11y()

Already checkA11y() allows you to audit and correct issues that might be on your page. As this my personal site is quite small, I only found two issues which were landmark-unique and heading order. However, the tool even allows you to check for unlabelled inputs, duplicate IDs and nested landmarks. See the available rules in the Axe documentation.

For more interactive sites, you might want to interact with the page first, for example, clicking on buttons to reveal other content, before running cy.checkA11y().

Github actions

To automate the process, I set up a Github action to check for every MR. You can learn how to set this up in the Cypress Documentation on Github actions. You can also check out the repo for this blog for my specific set-up, which is a static site running on 11ty.

For now I've only written the test so it checks the latest blogpost, as I don't really want the CI to run for too long and to get progressively longer as I write more posts (even though it is admittedly very short already, being a simple site). Check out that test on my Github repo for this site.

Further resources