Test Accessibility at Runtime with Selenium WebDriver and aXe-Core

Instructor: [0:00] To audit our app for accessibility issues at runtime, we can use Selenium WebDriver to run our application in a browser environment. Then, with the aid of the @axe-core/webdriverjs library, we can analyze the current page for any accessibility issues.

[0:14] To get started, we'll need to npm install selenium-webdriver and @axe-core/webdriverjs. We'll save that to our development dependencies. Through WebDriver, Selenium supports all major browsers on the market, such as Chromium, Firefox, IE, Opera, and Safari.

[0:33] Before you can get started using WebDriver, you'll need to install the necessary driver executables for which browsers you wish to test with. Then, you'll need to add these to your systems path. You can find the browser drivers to download here. I'm going to install the Chromium driver, for now. I'll need to find the version that I have installed on my machine.

[0:59] Now that that's downloaded, I'll need to place the executable in a directory of my choosing.

[1:12] Now, you'll need to add it to your system PATH. You'll need to open up your shell config file and add the location of where you downloaded your driver executable to the PATH variable. Here's my shell config. Here, I'm adding the location of where I put that executable to my PATH. Now that that's done, we can go ahead and start writing our tests.

[1:34] Selenium WebDriver is run via script, so we'll need to create a new script file. To start, we'll need to require Selenium WebDriver and aXe WebDriverJS. Since I installed the driver for Chrome, we'll go ahead and build the Chrome WebDriver instance. Now, we'll have the driver navigate to the page we want to test.

[2:04] Here, we're going to test our login page. The driver will return a promise. The promise will resolve once the page is finished loading in the browser. Now, we can call the aXeBuilder we imported from the aXe WebDriverJS library. It requires we pass it the WebDriver instance we created above.

[2:20] Then we can call the analyze() function, which will audit the login page against the aXe-Core rule set. The analyze() function is asynchronous and can either be passed a callback function, where it will provide the results as an argument, or it can be treated as a promise where the results will be passed when it resolves.

[2:37] All we're doing for now is just logging out the Results object so we can see what it looks like. To run the script, we'll need to run it with Node. Here's the WebDriver opening Chrome and navigating to the login page at the URL we provided. After aXe WebDriverJS finishes analyzing the page, it will resolve the promise with the Results object. Here's the Results object logged to the console as we specified in the script.

[3:01] The first property in the Results object is the inapplicable items. These were all of the rules that were found not to apply to the current page. There will likely be a lot of these. Keep scrolling, and eventually, you'll get to the incomplete items, which presumably would include any rules whose checks weren't able to be completed. For our case, there weren't any.

[3:19] Then there's this passes property listing all of the rules that did apply to the page and passed. Then, further down, you'll get to the test engine, test environment, test runner, timestamp, tool options and the URL being tested.

[3:39] Then finally is the violations property containing any rules that the page violated. Each violation lists the description and the detail about the rule, a URL where more information is available about this rule, the idea of the rule, how severe the violation impacts accessibility, and references to the exact nodes and tags of the source that violate the rule.

[4:01] Since these results are simply being output using console.log, we only see array rather than a more useful representation of the value. Now that we've seen what the Results object looks like, in logging the entire object to the console may not be the most useful format possible. We can use that to make our own report that shows us just the information that we care about in maybe a nicer format.

[4:22] Here's an example of a report using the Results object. Here, we're just pulling out the test environment, the timestamp that we ran the test and just the violations. We can add a nice header to our report. We can iterate over the violations, grabbing the impact of the issue, the details of the issue, the URL where we can find more information.

[4:45] We can iterate over that Node object, which if you recall, when we logged it to the console, all we saw was array. Now, we can dig into that and show the exact HTML of the elements that are violating the rule along with a summary of what we can do to fix the issue.

[5:02] Let's try running the script again and see what our report looks like now. Here's that header for our report, and here's the list of all of our violations, showing the severity, the description of the issue, the URL where we can go get more information, and the details of the element with the violation.