Your first accessibility scan with Cypress

Accessibility, often abbreviated as a11y (because there are eleven characters between the "a" and the "y" in "accessibility"), is about making sure a product can be used by people with a wide range of disabilities: visual, auditory, motor, speech, cognitive, and neurological.

It matters ethically, because excluding people from a service is a real harm. It also matters commercially and legally: accessibility broadens your audience and helps you comply with regulations like the Web Content Accessibility Guidelines (WCAG), the Americans with Disabilities Act (ADA), and the European Accessibility Act (EAA).

How common are accessibility issues?

Very common. The WebAIM Million study, which automatically analyzes the home pages of the top 1 million websites every year, consistently finds that around 98% of home pages have detectable accessibility failures. And six issue types account for the large majority of them, the same six this course is built around.

What automated tests can (and cannot) catch

We will catch these issues with axe-core, an accessibility engine that inspects a rendered page and reports rule violations. In this course we drive it from Cypress, via the cypress-axe plugin.

👨🏻‍🏫 Automated checks are a safety net, not the whole story. According to the axe-core documentation, on average you can find about 57% of WCAG issues automatically. It also flags some elements as "incomplete", where a human needs to review. Screen-reader testing, keyboard navigation, and real user judgment still matter. Automation is a great starting point, not a replacement.

Your first scan with Cypress and cypress-axe

With cypress-axe, an accessibility check is three steps: visit the page, inject the axe engine, then run the check.

Commands overview 📖

`describe`

Groups related test cases into a test suite.

Syntax:

describe(name, callbackFn)

Example:

describe('Accessibility', () => {
  // test cases go here.
})

`beforeEach`

Runs the given callback before each test (it block) in the same describe. Use it for shared setup, like visiting the page, so every test starts from the same clean, predictable state.

Syntax:

beforeEach(callbackFn)

Example:

beforeEach(() => {
  cy.visit('/')
})

`it`

Defines a single test case inside a test suite.

Syntax:

it(name, callbackFn)

Example:

it('reports no violations', () => {
  // test implementation here.
})

`cy.injectAxe()`

Injects the axe-core engine into the page under test. Call it after visiting the page and before any accessibility check.

Syntax:

cy.injectAxe()

Example:

cy.visit("/")
cy.injectAxe()

`cy.checkA11y()`

Runs an accessibility analysis on the page (or on part of it) and fails the test if any violations are found.

Syntax:

cy.checkA11y(context, options)

Example:

// Check the whole page.
cy.checkA11y()

// Check only a region of the page.
cy.checkA11y(".page")

👨🏻‍🏫 Both arguments are optional. With no arguments, cy.checkA11y() checks the entire page. Passing a selector as the first argument scopes the check to that region, which is handy when you want to focus on one component.

Exercise 🎯

With the local server running, create the cypress/e2e/a11y.cy.js spec and write a first test that visits the Banco Simulado app in its default state (accessible mode off) and runs cy.checkA11y().

Run the test and read the output. Because accessible mode is off, the check should fail and list several violations. Do not fix anything yet, the goal of this lesson is simply to see the six issues reported for the first time.

👨🏻‍🏫 With the DevTools open (Console tab) in the Cypress App's browser, click one of the individual error entries in the command log (for example, a11y error! html-has-lang on 1 Node) to print its details to the console:

Description:  Ensure every HTML document has a lang attribute
Help:         <html> element must have a lang attribute
Helpurl:      https://dequeuniversity.com/rules/axe/4.13/html-has-lang?application=axeAPI

If the Cypress App isn't open, use the npx cypress open command to open it.

Show the world what you learned 🌎

To show your professional network what you learned in this lesson, post the following on LinkedIn.

I started the "The 6 Most Common Accessibility Issues" course by @Bruno Pulis at the @Talking About Testing School, where I ran my first automated accessibility scan with cypress-axe and axe-core. #TalkingAboutTesting #TATSchool #A11yTesting #Cypress

👨🏻‍🏫 Remember to tag me in your post. Here is my LinkedIn profile.

How common are accessibility issues?

What automated tests can (and cannot) catch

Your first scan with Cypress and cypress-axe

Commands overview 📖

`describe`

`beforeEach`

`it`

`cy.injectAxe()`

`cy.checkA11y()`

Suggested content 📚

Exercise 🎯

Show the world what you learned 🌎

Quiz