Cypress: Automated Accessibility Testing

ACCESSIBILITY TESTING, in short A11Y Testing(because it has 11 letters between a & y :)) is a separate section that holds a big responsibility.

What is A11Y Testing?

Ask ten accessibility professionals what accessibility testing is, and, you’ll get ten different answers. Some will emphasize usability. Some will tell you it’s a code quality problem. Others may say it’s all about compliance and check lists. I still find it hard to answer this question.

No, it’s not because we don’t have standards. We have several standards that different nations have come up with. So Accessibility testing is a type of software testing performed to make sure an app complies with recommendations of the so called standards. Segment 508 and WCAG rules are the main standards being used in the world.

Section 508 is the availability standard characterized by the US government, to ensure that all US government sites can be gotten to by people with disabilities.

Web Content Accessibility Guidelines or WCAG characterize the norms for openness for people, associations, and governments around the world. WCAG 2.0 has been acknowledged as an International Standards Organization (ISO) standard, and numerous nations have embraced WCAG 2.0 as their lawful standard for web openness. (WCAG 2.1 available by now)

Why we need A11Y Testing?

As a rule, applications that are used by a wide range of people, including people with disabilities are made to be adapted. Apart from the fact that accessibility allows for the expansion of the number of users of an application, many companies think it is a great marketing move. Accessibility gains companies more trust and in return, more reaches from the outside world.

Accessibility is, usability. I think, accessibility often helps not only people with disabilities, but also any other people under certain circumstances. For example, the one could watch a video with subtitles when it’s noisy and there are no headphones at a hand. Or, alternatively, when there is no opportunity to read something, you could just listen it through headphones. Applications are often adapted for users with hearing and visual impairments, and, less often, for people who are not able to use a keyboard or any other manual input device.

How to test A11Y?

As mentioned before, testers test the apps for the compliance with the selected standards. There are lots of rules in each standard to be checked and often the testers fight on Internet chat channels over whether an element should have been coded as a button or a link! Haha.. This is serious!

There are lots of tools to do the a11y testing now. Each tool gives you the capability to pick a standard or several standard to run a test on the app. And it will generate a report as well. So how about doing this manually every time the app changes.. C’mon! Seriously.. Over and over again! Then what about the reports?

Yes, it’s a pain in the head! B’coz you have to be keen on watching for a11y issues manually. That’s why the Automated A11Y testing has come to the lime light. Thank GOD!

Automated A11Y Testing with Cypress

Cypress as you might already know, is an emerging test automation tool. Cypress officially have a plugin for this purpose and more importantly it’s pretty simple to setup the whole thing.

The plugin used in Cypress for a11y testing is cypress-axe which uses the axe-core of Deque Labs. Axe is an accessibility testing engine for websites and other HTML-based user interfaces. It’s fast, secure, lightweight, and was built to seamlessly integrate with any existing test environment so you can automate accessibility testing alongside your regular functional testing.

Automated accessibility testing is a huge time-saver, it doesn’t require special expertise, and it allows teams to focus expert resources on the accessibility issues that really need them. Unfortunately, most accessibility tools are meant to be run on sites and applications that have reached the end of the development process and often don’t give clear or consistent results, causing frustration and delays just when you thought your product was ready to ship.

Axe was built to reflect how web development actually works. It works with all modern browsers, tools, and testing environments a dev team might use. With axe, accessibility testing can be performed as part of your unit testing, integration testing, browser testing, and any other functional testing your team already performs on a day-to-day basis. Building accessibility testing into the early development process saves time, resources, and all kinds of frustration.

Installing and Configuring ‘cypress-axe’

It really easy to install and configure..

First run the following commands to install cypress-axe to your test project:

Add as a dev dependency:

npm i -D cypress-axe

Install peer dependencies:

npm i -D cypress axe-core

Configure on cypress:

Open the ‘cypress/support/index.js’ file and add the following command at the end.

import 'cypress-axe'

Now you are done installing and configuring the plugin. Pretty easy huh?

A11Y Standards on Cypress-Axe

Cypress-axe or the axe-core engine supports following accessibility standards:

WCAG 2.1

WCAG 2.0

Section 508

Apart from that it also have it’s own standards as best-practices, experimental and cat. More information on those can be referred from here.

Cypress-Axe Commands

Cypress-Axe have the following commands to do the a11y testing:

cy.injectAxe

This will inject the axe-core runtime into the page under test. You must run this after a call to cy.visit() and before you run the checkA11y command.

You run this command with cy.injectAxe() either in your test, or in a beforeEach, as long as the visit comes first.

cy.configureAxe

To configure the format of the data used by aXe. This can be used to add new rules, which must be registered with the library to execute.

cy.checkA11y

This will run axe against the document at the point in which it is called. This means you can call this after interacting with your page and uncover accessibility issues introduced as a result of rendering in response to user actions.

Parameters on cy.checkA11y (axe.run)

context: (optional) Defines the scope of the analysis — the part of the DOM that you would like to analyze. This will typically be the document or a specific selector such as class name, ID, selector, etc.

options: (optional) Set of options passed into rules or checks, temporarily modifying them. This contrasts with axe.configure, which is more permanent.

More details can be found here..

Let’s write our first a11y automation script

Are you ready to roll out..? Okay.. let’s go on..

First, let’s define the standards we are going to use as follows:

const A11YOptions = {
    runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa', 'section508']
    }
}

According to the above code, we are testing our app against WCAG 2.0 Level A, WCAG 2.0 Level AA and Section-508 standards.

Now, lets write the test case..

beforeEach(() => {
  cy.visit('https://localhost:9000')
  cy.injectAxe()
  cy.configureAxe
  ({
    reporter: "v2",
    iframes: true
  })
})

it('Check a11y violations on load', () => {
  // Test the page at initial load
  cy.checkA11y(A11YOptions)
})

In the above code, we visit, inject and configure axe in beforeEach and it checks for the a11y issues on page load. As we have passed the A11YOptions to the cy.checkA11y() method it checks with the given standards. If parameters are not passed it will check with all available standards including best-practices, cat and experimental.

Now, we have validated a11y issues on page load. We have to validate the a11y issues after performing actions as well. So let’s do it!

it('Has no a11y violations after button click', () => {
  // Interact with the page, then check for a11y issues
  cy.get('button').click()
  cy.checkA11y(A11YOptions)
})

After adding the above test case, it validates the app for a11y issues after button click. Like wise you can add the a11y tests to you test cases where ever needed, and this will detect your a11y issues while you run your functional tests.

Phew! No hassles.. Cool right! Let’s give it a run..

End Results

After your test script complete execution you could see something like below on your cypress test runner..

The command log of the cypress test runner displays the a11y issues detected as above. If you want to have more details on the issues, you can click on one a11y issue and open the browser dev tools console. Then you can have a detailed information on the issue and the ways to avoid the issue.

Click on the “Nodes” option in the console to see all the elements /nodes having the a11y issue. So you can fix those issues easily as you know where exactly the issue has aroused.

That’s it from this article! Happy testing..