How to Test Accessibility With Axe in Cypress

Cogworks QA professional, Aga, explains why web accessibility is so important in software development testing and recommends the perfect tools to get started.

Why is web accessibility important?

We live in times where access is so important, both online and in the physical world. Paying attention to accessibility gives people of all abilities the tools to participate, which creates opportunities. 

In digital, accessibility is the practice of making a website usable by everyone and it can focus on improving a website’s clarity from the perspective of those with visual, hearing, mobility, or cognitive impairments (or without disabilities). Desirable features of an accessible site include things like, correct contrast levels, ordered headings, aria-labels, responsiveness keyboard and accessibility. 

According to Scope, there are 14.1 million people in the UK with disabilities (that’s 20.6% of the UK population!). Reaching such a large group of recipients is vastly important, especially from a business point of view. Apart from showing care for people and striving for the highest standards, it can improve SEO and enable website use on various devices. 


Web accessibility testing tools.

To test websites against criteria, there are a wide range of modern testing tools available to help companies like ours produce the best digital solutions. You can use tools that are commonly used by people with disabilities, like a keyboard or screen reader. There are also browser extensions like Axe or Lighthouse which run accessibility checks.

For automated tests in your software development process, I think Axe-Core is the most useful. Many projects are built on top of the Axe-Core, so no matter if you use Selenium or WebdriverIO or another automated testing framework, you can implement Axe to your tests! 


What is Cypress?

Cypress is a modern testing framework, which enables writing end-to-end tests in an intuitive  way. Even testers with a very basic programming background can successfully write valuable tests using Cypress; it’s quick and easily integratable with any CI/CD process. Plus,  it  allows integrating external libraries, like Cypress Axe.

Set up and run tests with Axe in Cypress.

Installation and Setup 

Before you start with Cypress Axe, you need to install Node and npm and initialise your test project. Once you have this done, install Cypress from npm:

npm install --save-dev cypress

Install Cypress-axe:

npm install --save-dev cypress-axe

You will need to install the Axe-core as well:

npm install --save-dev axe-core

Then open Cypress. This command creates Cypress catalogue and cypress.json if you open Cypress for the first time:

./node_modules/.bin/cypress open

Once you have done this, you should see the following Cypress structure in your project:

The integration catalogue is the one where all of your tests will be stored. Cypress provides multiple basic and advanced examples, which you can use.

But let’s go to the Support catalogue first - in support/index.js add the following statement:

import 'cypress-axe'

To open Cypress easier in the future go to package.json in your project and add the following command under scripts:

"cypress:open": "cypress open"

This will create a npm script that you can access from your code editor (e.g. Visual Studio Code) and will open Cypress test runner with all test files:

Writing and running tests with Cypress Axe.

Writing tests with Cypress Axe is the same as conducting usual Cypress tests!

In the integration catalogue create a new file,  "accessibility.spec.js" (use the Mocha structure with “describe” and “it” blocks).

Next, you need to command Cypress to visit a page you want to test with cy.visit(url); and then use cy.injectAxe(); to inject Axe-Core runtime to the page. Those commands are repeated for every test case, that is why you can store it in “beforeEach” block. 

Now, add cy.checkA11y(); command in “it” block, which will run its accessibility checks on the page, like aria attributes, colour contrast, keyboard accessibility, image labels, headers, visibility and more!

/// <reference types="cypress" />
describe(‘Page accessibility tests’, () => {
  beforeEach(() => {
  it(‘Should have no accessibility violations’,() => {

Save the above code, open Cypress test runner and run your test.
This is an exemplary test result, which points out violations against desirable aria attributes usage, heading order, link name and list. It means those elements can impair the legibility to people with disabilities. Clicking on each error (displayed as “a11y error!” in the below image) will show the affected area on the page. 


To learn more about the errors, go to DevTools (right-click / Inspect). The Console tab will show you the impact, error’s description and hint how to fix it. Here’s a couple of examples of failed tests and what you can do about it:

Example 1.

If the description reads “Ensures links have discernible text” the link on the page has no visible text - that might be the case if there is a search icon without text “Search” linking to the search.


Example 2.

If the description reads "Ensures that lists are structured correctly”; it means the test has failed and the list must be structured in some other way. “<ul> and <ol> must only directly contain <li>, <script> or <template> elements”. If this test fails, it means the list is structured in some other way. Both violations can cause problems for those who rely on screen readers to access information online.  

Now you know how to get started with Cypress Axe! There’s plenty more to learn, and the application provides more configuration options that you can easily apply to your code. You can for instance specify the page elements you want to test with command:


or exclude some with command:

cy.checkA11y({exclude: [‘.class-name’]})

To check all of the possibilities of Cypress Axe, check out the documentation! 

Thanks to test automation with Cypress, accessibility testing can be easy. Such important website standards checks should not be abandoned (especially if they can be covered with just a few lines of code).

If you’re in the mood to learn more about software development testing, I highly recommend The Quick Guide to Visual Regression Testing With Cypress, and Getting started with visual regression testing and WebdriverIO.

For more resources from our development, frontend and QA team at Cogworks, head to the blog.



  • Image for 3 Ways to Win Consumer Trust With Your Website Strategy

    3 Ways to Win Consumer Trust With Your Website

  • Image for Keeping Up With Digital Transformation Build

    Keeping Up With Digital Transformation

  • Image for How to Use Google Chrome Lighthouse for Better Web Performance Build

    How to Use Google Chrome Lighthouse for Better Web Performance

  • Image for Azure Resource Naming Tips 2022 Build

    Azure Resource Naming Tips 2022

Ready to collaborate ?

Get in touch to see how we can transform your digital presence.

Send us a message