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
cy.checkA11y() has already helped me find hard to notice issues such as heading order.
The tools at play
- Cypress is an end-to-end testing framework which allows you to run tests in the browser, as if they were clicking through your app or website.
- Axe-core brands itself as "an accessibility testing engine for websites and other HTML-based user interfaces". The engine can be accessed in several different ways including the VSCode Accessibility Linter, which will make suggestions as you write code, and the axe DevTools, which allows you to run audits of websites directly from your browser dev tools.
- cypress-axe is the module which allows you to inject the axe-core runtime into the page you are testing in Cypress.
Setting it up
To avoid copy-pasting documentation which might change, I suggest you follow the documented installation steps for
Cypress and then for
After installing, you will need to add the below line to
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()
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
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.
- Testing Accessibility with Marcy Sutton. A livestream from Jason Lengstorf's Learn with Jason series. Marcy is an expert in web a11y and I highly recommend her content on the subject.
- The most common HTML mistake that I see, by Kevin Powell. This video is where I first learned that heading order is a very common issue in accessibility. Kevin audits a couple of sites, one good example and one bad example, and explains why this is an issue