Axe 3.0 has arrived — here’s what you need to know

The Deque labs team has been working hard on some updates to the aXe-Core JavaScript testing library for 3.0, including support for Shadow DOM and web components, improve performance, and some new rules: both experimental rules, best practices, and we’ve got more coming after 3.0.

To make sure that you’re ready to hit the ground running with aXe 3.0, we’re going to look at how these API changes work; how they impact our browser extensions and other integrations; as well as our Attest product line, so that way you’ll know what’s in aXe 3.0, how you can hit the ground running, and have an even stronger suite of accessibility testing tools. Let’s get started.

Axe 3.0 & Shadow DOM

To talk about what’s new in aXe 3.0, we need to first talk about what’s new in the aXe-Core JavaScript library. It is the underlying JavaScript that powers our browser extensions and accessibility test APIs.

In aXe-Core 3.0, the biggest change is that it now supports Shadow DOM, which might sound spooky, but it is a standard that’s part of the web component specifications that allows you to encapsulate portions of web pages. You can think of web components as the jQuery plugins of the future, and Shadow DOM is the portion of them that prevents your styles and scripts from leaking inside or out.

Example: aXe-core 3.0 in Shadow DOM

To show you how this works in practice, I’ve got this little ski trip organizer demo app that I made with React JS, and I’ll just go inspect it to see what’s happening in the DOM inspector in Chrome.

If I zoom in a little bit you can see that this trip planner component has this encapsulation inside with an open shadow root. Open–as opposed to closed–shadow root, encapsulates these pages but still allows tools like aXe-Core to step inside of them. So, there are some known accessibility issues in this component that we should be able to catch with aXe-Core 3.0.

aXe-Coconut Extension and Shadow DOM

To show you how this works, I’m going to open up our aXe-Coconut pre-release extension which up until now has been the way to test aXe-Core 3.0 in this pre-release environment. Eventually, these changes will land in our stable axe DevTools for Chrome and Firefox extensions so you can test inside of Shadow DOM with the normal extension.

But for now, we can look at this in aXe-Coconut and see that it does step inside of Shadow DOM; it found that we were missing some form labels and even some color contrast issues inside of this shadow root. From aXe-Coconut, I can go and inspect the node and find that, yep, sure enough, aXe-Core found this issue inside of our open shadow root. No longer will aXe skip over these entire regions of pages if you are indeed using open Shadow DOM.

Filing Bugs in Axe-Coconut

One other cool thing I’ll point out in the new aXe-Coconut extension is this little bug report button. The bug report button allows you to file an issue about an experimental rule or Shadow DOM issue straight from the browser extension.

Unlike our regular Chrome extension that doesn’t have that bug report button, aXe-Coconut is intended to give you an opportunity to file bugs early, before these changes roll out to everyone. You will have Shadow DOM support in our aXe Chrome and Firefox extensions very soon, and they are already in aXe-Core 3.0.

Axe 3.0 in your automated test suite

So far we’ve been focused on the browser extensions and sort of manual process of accessibility testing. However, you can also make use of aXe 3.0 in your automated test suite. To do that, let’s go over to my text editor where I’ve got some integration tests written for our little demo app, built with React.

In the package.json file, I’ve got a script here for integration. It runs the Mocha test framework and then our arbitrary integration/a11y.js file. I’m also pulling in a special version of aXe-WebdriverJS. Now this will become standard in our stable 2.0 release of aXe-WebdriverJS, but until now you’ve been able to use aXe 3.0 in this 2.0.0-alpha.1. That will become mainstream very soon, but for now, I can use this alpha.1 with the aXe-WebdriverJS tool to actually test inside of Shadow DOM with an automated test.

In our integration/a11y.js file, I’m using Selenium Webdriver and aXe-WebdriverJS to run a real browser instance and test for accessibility from the command line. I do a bit of setting up here, and I’ve covered that in other videos so I won’t go too deep into this right now, except to show you these actual tests. The first test says it should find no violations on the home page, it goes and finds an element on that page, and runs this axeBuilder.

How to Run axeBuilder

Just like a normal accessibility test, we expect that it has zero accessibility violations. And then to make sure we’re testing all of the different areas of this application, there is the modal window in this app, so we go and programmatically open the modal window with the enter key, and then we run axeBuilder again to make sure it has no violations. Now, I did write this up intentionally with accessibility violations so we should see a bunch, and they should look like what we saw in aXe-Coconut.

In my terminal, I am going to do npm run integration to run that npm script. It’s going to open a browser in instance in the background, we can see it open once for each test, and if I scroll up, yep, unfortunately, there are some accessibility issues here, but that was the goal. We wanted to see how aXe-WebdriverJS would report these to us.

So, in this app I’m just going to scroll up to the top here, I can see that it is indeed finding those same label issues that we saw in aXe-Coconut. It’s going into this trip planner and telling us that we forgot some labels. So that’s an issue that we could fix. We could uncover more issues by either using the browser extensions, or in our automated tests, and then you can go and fix all of these, try to get it so that you have no accessibility issues.

Summary

In this format, you could prevent accessibility issues from being deployed out to production or maybe fail a build before it gets approved in a pull request. It really depends how your team wants to work, as to which tools you like to use: do you prefer browser extensions or automated tooling, or some combination of both? That’s my M.O., typically. But with aXe 3.0 you can really modernize your workflow so that it’s stepping inside of Shadow DOM and doing it as fast as possible. There’s a lot of edge cases that we’re working on so if you find any issues, you know, false positives or false negatives, definitely let us know, either on GitHub or on Twitter. We would love to hear from you. Thanks so much.