This week we begin a series of blog posts about accessibility and Cypress. In upcoming posts we’ll discuss open-source accessibility plugins for the Cypress App, patterns of adopting accessibility testing that we have seen be successful in working with customers, how automation fits into an overall accessibility strategy, and more.
In today’s post, we’ll share examples from our new Cloud product, Cypress Accessibility – recently launched at CypressConf 2024 after a long early access period. You’ll come away with a good understanding of what’s possible in accessibility reports in Cypress Cloud and get live links to every example so you can explore for yourself, and see how this can help you detect and fix issues that may prevent people with disabilities from using your application successfully.
How it works
First, let’s explain what’s going on when a Cypress Accessibility report is created. This is a completely server-side process, based on the Test Replay artifacts that are uploaded to Cypress Cloud as part of a standard test run for a Cloud-linked project.
As this video shows, simply writing and recording tests is enough to generate detailed page- and component-level reports based on everything that was rendered during your Cypress tests.
As the run is recorded of the individual states and variations of your application are tested with Axe Core® for a set of potential violations of the Web Content Accessibility Guidelines (WCAG), then the results are merged together to form a single sortable, filterable report for the run.
There are no plugins to install and no special test code to write - your tests are not impacted in any way.
Important Workflows
Each time you look at an accessibility report, you may have different questions you want to answer, or different goals you want to accomplish. Here we’ll talk about some of the main things people do in Cypress Accessibility.
Find the page with the most important issues
In our demo app, the homepage has the most issues. In total there are 15 issues detected on the page, which Axe Core® splits into four severity levels - Critical, Serious, Moderate and Minor. This breakdown helps with understanding at a glance which pages have the most problems that need attention, and how serious those might be for disabled users.
Here's a video demonstration of how this works:
Explore this list of pages in the Realworld App Cloud project.
Find the rule that is failing the most often
In this example, we can see that the Realworld App has got 5 critical failing rules, and one that needs manual review. By far the most widespread problem is images missing alternate text. This is a big problem with this application because people with visual impairments or certain other disabilities depend upon accurate alternative text to understand the meaning and purpose of elements like images and icons.
See these failed rules in the Realworld App Cloud project.
Debug an issue
Let’s pick a critical issue like “Buttons must have discernible text”. This text is necessary for assistive technology to correctly present what actions can be taken, and carry out those actions. When we click into the report, we see details about the issue and some possible solutions. We also have a live HTML and CSS example for each element with the issue - in fact we have access to all 49 examples of times this issue was detected as different tests moved through the application.
Since these examples are live DOM, we can debug the problem and find the solution right there in the browser:
Here’s a link to the exact issue in question - everything you see in Cypress Accessibility is easy to deep link to so you can share the issue.
Summary
We've seen how to check page and rule level results and see detailed examples of every issue. This is just some of the functionality available in Cypress Accessibility: see our documentation to learn more about how these results can be used to fail CI jobs, and learn about the full range of functionality.
Contact us for a trial if you’d like to see how this works with your own projects, with no configuration or setup required.