I don’t believe I’ve mention this before here, but I am a huge fan of Hey. By far the best email service I have ever used. What makes Hey even cooler is the team behind Hey sharing they engineering approach to different problems. Be that through various tweets or blog post like Scaling the hottest app in tech on AWS and Kubernetes which outline how they use k8s. Recently, they shared how to tackle ay11 under hey accessibility is a lot of work. One thing that stood out was to me was their usage of axe-core. Axe-core is an accessibility engine for automated Web UI testing. Which reminded me of playwright, so I started to wonder if the two could be combined, turns out they can be. Let’s explore how to do that.
I’m going to reuse the project I created in my last playwright post, it already has few test and has been configure to use other packages like Mocha and Chai. To get started, axe-core needs to be installed, you can use the following command.
With axe now installed I can start building some test. I’ll add new file under the test folder, I’ll call it a11y.ts. I’ll start by importing the required packages need for our test.
Next, I’ll need to configure playwright’s browser and page object to run before and after each test. That can be done like this.
Base on the axe docs, I need to include axe.min.js in any fixture or test system. That file can be loaded from the node_modules folder using node’s own file system module.
For example, if you wanted to get the value of a document’s href that is running under the browser context loaded into a playwright context, you would do so like this.
For more information see the playwright docs on execution context.
The evaluate method can take a string or a function as an optional argument. I can use file system to read axe.min.js into memory as a string, then pass that as an argument on the evaluate method. This is how I can get axe.min.js to be included.
Now comes the next trick, and that is that I need to run axe under the context of the browser, see #1638. That means we have to use the evaluate method again. The problem here is that when the test are executed, axe will run under the playwright context, and will not be available under the browser context. The solution to this problem is to extend the window interface to include axe, see How to declare a new property on the Window object with Typescript for more details.
I’ll use the following code to include axe under the window interface.
Putting everything we have talked about so far together yields the following test.
Let’s review what the test above is doing.
- Playwright’s page object is used to nagivate to google.com.
- Node’s file system is used to load axe.min.js.
- axe.min.js is injected onto the browser context using evaluate method.
- axe.run is executed by providing it with document context.
- Assert that no a11y violations were found on google.com.
The a11y.ts file should now look like this.
As always, to execute the a11y test, plus the test that already existed on the project run ’npm test’. If you run that command you will notice the following output.
The test failed, I can use console.log to spit out the violation. Running the test again yields the following result.s
Awesome. I can now do a11y testing while using playwright. You should know, that the example above is the most basic a11y test you can create. Axe is a very powerful library that offers many configurations. You can take the code above and expand it by passing different configurations to the run method. Or you can take a different approach, that is to leverage an existing library that does most of the heavy lifting for you, a library like axe-playwright.