products

Testing A11y Using Cypress And wick-a11y Plugin

Add accessability testing in 60 seconds using the wick-a11y plugin.

I have a little web app called Gametime I use to keep track of players during youth soccer matches. Recently I decided to add a11y testing to ensure the text is readable, inputs have labels, etc. Since I already had Cypress end-to-end tests covering all features of the app, I just needed 60 seconds to ensure the web app is accessible to everyone.

Install the wick-a11y plugin

First, let's install wick-a11y plugin.

1
2
$ npm i -D wick-a11y
[email protected]

Register the plugin's tasks in the Cypress config file

cypress.config.mjs
1
2
3
4
5
6
7
8
9
10
import { defineConfig } from 'cypress'
// https://github.com/sclavijosuero/wick-a11y
import addAccessibilityTasks from 'wick-a11y/accessibility-tasks'

export default defineConfig({
  ...
  setupNodeEvents(on, config) {
    addAccessibilityTasks(on, config)
  }
})

Include the plugin's custom commands by importing it from the support file loaded by the browser

cypress/support/e2e.ts
1
2
// https://github.com/sclavijosuero/wick-a11y
import 'wick-a11y'

That's it. Now I can confirm the page is accessible by calling cy.checkAccessibility() command.

Check a11y

Let's confirm the Teams page works for everyone. I simply add the accessibility command at the end of the test

1
2
3
4
5
6
7
8
9
it('enables Add button when typing the name', () => {
  cy.visit('/team/')
  cy.get('[data-cy="teams-container"]').should('be.visible')
  cy.contains('button', 'Add team').should('not.exist')
  cy.get('[name=teamName]').type('Name')
  cy.contains('button', 'Add team').should('be.visible')

  cy.checkAccessibility()
})

Right away it shows 1 critical problem: the text "Zero players" has a color that is hard to read on white background.

Color contrast problem

You can get the error details by clicking on the "Fixme" log line in the Command Log

A11y error details

The fix is simple: use a darker gray color class

1
2
3
4
5
6
7
  <div
    data-cy="zero-teams"
-   class="flex h-24 items-center justify-center text-gray-400"
+   class="flex h-24 items-center justify-center text-gray-500"
  >
    No teams yet
  </div>

Note: this plugin by default checks. If you want to see lower severity errors, enable them when running the command; could be verbose at first.

1
2
3
4
5
6
cy.checkAccessibility(undefined, {
  // fail on critical errors
  includedImpacts: ['critical', 'serious'],
  // only warn for non-critical errors
  onlyWarnImpacts: ['moderate', 'minor'],
})

Our page is missing <main> landmark (and other landmarks, like <footer>), so we get several warnings, highlighted in yellow

Low level A11y errors

Detailed reports

This plugin generates detailed static HTML reports (which you can control). Open the report file from cypress/accessibility folder. Each error has a separate section, showing the HTML snapshot with offending element.

Text contrast violation

I suggest saving cypress/accessibility folder as a test artifact on your CI. If the cy.checkAccessibility command fails, these reports will make fixing it a breeze.