Accessibility Knowledge I Learned from Automatic Accessibility Testings with Cypress and cypress-axe
I wanted to use Cypress to run automatic accessibility tests with Cypress and cypress-awe on my Web Components project Cucumber Components. Before I wrote any tests for Cucumber Web Components, the test reported several serious a11y errors on the components documentation page itself. I need to fix these accessibility issue first before moving on to web components testing. So this is probably the best time to start a new article sharing the a11y errors and learn some accessibility knowledge.
1. <ul>
and <ol>
must only directly contain <li>
, <script>
or <template>
elements.
Command: a11y error!
Id: list
Impact: serious
Description: Ensures that lists are structured correctly
Help: <ul> and <ol> must only directly contain <li>, <script> or <template> elements
Helpurl: https://dequeuniversity.com/rules/axe/4.7/list?application=axeAPI
failureSummary: "Fix all of the following:\n List element has direct children that are not allowed: a, h2"
html: "<ul class=\"astro-RYJZJGVK\">"
This error here is I was using <a>
tag and <h2>
tag as direct children of <ul>
element. So I need to move these two elements elsewhere.
<ul class="astro-RYJZJGVK">
<a href="#article" class="sr-only focus:not-sr-only skiplink">
<span>Skip to Content</span>
</a>
<h2 class="astro-RYJZJGVK">Components</h2>
<li class="astro-RYJZJGVK">
<a href="/components/alert" class="astro-RYJZJGVK">Alert</a>
</li><li class="astro-RYJZJGVK">
<a href="/components/button" class="astro-RYJZJGVK">Button</a>
</li><li class="astro-RYJZJGVK">
<a href="/components/checkbox" class="astro-RYJZJGVK">Checkbox</a>
</li><li class="astro-RYJZJGVK">
<a href="/components/carousel" class="astro-RYJZJGVK">Carousel</a>
</li>
<!-- other existing li elements -->
</ul>
2. Ensures links have discernible text
Command: a11y error!
Id: link-name
Impact: serious
Tags: Array(9)
Description: Ensures links have discernible text
Help: Links must have discernible text
Helpurl: https://dequeuniversity.com/rules/axe/4.7/link-name?application=axeAPI
failureSummary: "Fix all of the following:\n Element is in tab order and does not have accessible text\n\nFix any of the following:\n Element does not have text that is visible to screen readers\n aria-label attribute does not exist or is empty\n aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty\n Element has no title attribute"
html: "<a href=\"/\" class=\"logo astro-RYJZJGVK\">\n\t\t\t<img src=\"/cucumber-components.svg\" role=\"presentation\" alt=\"\" class=\"astro-RYJZJGVK\">\n\t\t</a>"
The error is I didn’t add a discernible text inside my logo link.
<a href="/" class="logo">
<img src="/cucumber-components.svg">
</a>
To fix this accessibility issue, I need to add a discernible text.
<a href="/" class="logo">
<span class="sr-only">Cucumber Components Home Page</span>
<img src="/cucumber-components.svg">
</a>
3. Ensure elements that have scrollable content are accessible by keyboard
Command: a11y error!
Id: scrollable-region-focusable
Impact: serious
Description: Ensure elements that have scrollable content are accessible by keyboard
Help: Scrollable region must have keyboard access
Helpurl: https://dequeuniversity.com/rules/axe/4.7/scrollable-region-focusable?application=axeAPI
failureSummary: "Fix any of the following:\n Element should have focusable content\n Element should be focusable"
html: "<pre class=\"language-html\">"
For codes snippets like below, they’re scrollable, so we need to add a tabindex=0
to allow keyboard access. Be sure to add a focus indicator in CSS as well.
<pre class="language-html" tabindex="0">
<cc-select>
<cc-option value="monday" text="Monday" aria-selected="true"></cc-option>
<cc-option value="tuesday" text="Tuesday"></cc-option>
<cc-option value="wednesday" text="Wednesday"></cc-option>
<cc-icon icon="chevron-down" slot="suffix"></cc-icon>
</cc-select>
</pre>