How to Run Accessibility Testing in Storybook With Addon-a11y

[00:00 - 00:26] Something we should always test in our applications is accessibility. Access ibility testing is a type of software testing to ensure that your application is usable by as many people as possible, including people with visual disabilities and other kinds of impairments. Also known as A11Y, often times developers don't think about it when writing their components, which can result in, for instance, a payment form which is not accessible by screen readers, preventing blind users to buy products in your application.

[00:27 - 00:43] Building accessible applications is a social responsibility and is part of the law in many countries, and there are many types of accessibility issues that applications might have. Here's a restaurant card. It looks nice and you can read information in it. Let 's change the color of the text to white.

[00:44 - 01:02] The color contrast is so low that I'm pretty sure you're having a hard time reading it. Can you imagine how worst this could feel for people with visual impairment? Here's a form that tells which fields are required by using the red color. But what about users that don't see color? We should use more indicators like an asterisk instead.

[01:03 - 01:26] Accessibility is a very important topic that we should always think about. I know sometimes it's difficult to remember, but there are tools to help us get there. Accessibility is the most used accessibility engine that helps detect a lot of accessibility issues and helps educate you how to fix them. And in this lesson, we'll learn how to integrate Axe into Storybook so we can always keep a close eye in our components accessibility. Let's get to it.

[01:27 - 02:00] When looking for integrations, we can always go to the official Storybook website and go to the add-on gallery. In the popular section, we already see accessibility, which is exactly what we're looking for. Accessibility add-on allows you to integrate Axe into Storybook and get a visual overview of the accessibility errors or passes in your stories. So let's go ahead and edit to our project. We essentially need to install the add-on, which is yarnaddsstorybook/addonA11Y as a dev dependency. So let's go to our project, open a terminal, and if you have Storybook running, just kill it and then add that dependency.

[02:01 - 02:26] The next step is to register the dependency in the main file. So let's just copy this right here and go to our main file under Storybook main. And then in the add-on section, we just register the add-on A11Y. And that's it . Now the add-on panel should be working. It's as simple as that. So we just need to run Storybook and we should see a new accessibility panel. So let's run yarnstorybook and wait for it to open.

[02:27 - 02:48] So let's visit the restaurant card and look at the add-on panel. Over here, you see that we now have a new tab called Accessibility. And as you can see here, the component is good. It's got the accessibility checks, which are all passing . But as an experiment, let's make it fail. So let's go to the implementation of the restaurant card under Source, Components, and then Restaurant Card.

[02:49 - 03:23] And then at the bottom, you should see a restaurant image that contains an alternative property. So let's just remove it. And when we're looking at the accessibility panel, this should be rerunning, including the violation that we have. And if it does not rerun, you can click on Test Completed. And that's just going to rerun the accessibility tests. And over here, we see now we have a violation. So once we expand this, and also we can click here to highlight the element, which has the accessibility violation, we get the explanation of what is going on together with the priority of the issues.

[03:24 - 03:40] And not only that, we actually have a link that explains us further and educ ates us exactly what is the issue and how to fix the problem. So let's go back to our stories and fix the accessibility issue. And now we can also rerun the accessibility here and see that everything is passing.

[03:41 - 04:00] What's great about the accessibility add-on is that it provides you this new option in the toolbar, which gives you different kinds of filters for different kinds of visual impairments. So for instance, deuteronomally, it's a type of impairment where people don't see specific colors. And the same goes for protonomally, or maybe even graysc aling because people might not be able to see colors.

[04:01 - 04:15] And another thing that we can do here is, for instance, we go to the restaurant detail page and some users might be elder and have a blurred vision. So this filter allows us to simulate that, and we should make sure that the elements stand out and the applications still usable for them.

[04:16 - 04:35] And this is a great tool to have in any storybook. Essentially, you can use this for your own sake so you can develop more accessible components, but you can also share all these kinds of functionalities with the designers in your team so they can also get more education about it. And you might be asking, "That is great, but I also don't want to manually check every single accessibility issue for my components. That might be too much trouble."

[04:36 - 04:55] So how can we automate the checking for us? Well, in the previous lesson, we learned about the test runner and we can use its experimental hooks in combination with other tools to automate the accessibility testing of our components. So the test runner allows us to have a new file which is called test-runner.js under the storybook folder.

[04:56 - 05:17] And this configuration expects the module.exports to be returning an object containing a couple of things. First of all, an asynchronous pre-render function that receives the playwright page and we can do a lot of things with it, as well as an async/post-render function which also has access to the playwright page.

[05:18 - 05:33] And these are the hooks from the test runner. The pre-render will execute before the component renders and the post-render will execute after the component renders. And because we're using playwrights, there is an accessibility playwright integration called "X Playwrights" that we can just install and use in our projects.

[05:34 - 05:53] So let's just go ahead and do it. So we essentially get this and we go to our terminal, we kill storybook, and we do yarn add as a developer dependency "X Playwrights". And then we can use this dependency over here. So let's just get it, we're using require, "X Playwrights".

[05:54 - 06:05] And then we can use two things, check accessibility as well as inject "X". So we want to make sure to inject "X" in our page before the component renders.

[06:06 - 06:14] So let's just await it. And once the page is rendered, what we want to do is we want to check the accessibility of our page and also let's await it.

[06:15 - 06:21] And the function receives the selector of the element to test accessibility of. And in storybook, the wrapper of a story has an ID of root.

[06:22 - 06:48] And also optionally, you can pass some options. So we want to have a detail report. And also the detail report options, we want to get the HTML as a result so that we can know exactly what element in our component has the violation. So now let's run storybook again. This time storybook -ci so we just don't open the browser. And once it's done, we open a new terminal and we run "Yarn Test Storybook in Watch Mode".

[06:49 - 07:12] So now let's go back to the restaurant card and cause the accessibility issue once again. As a result, we should see some failures in the terminal and it will tell us exactly what are the elements and the font size is not really helping but you can get an idea that there is an element violating the rule of which image elements should have an alternate text, which we're not added.

[07:13 - 07:31] So basically let's go back and fix the accessibility issue just by adding the out property again and now the tests are passing. And there you go. We now have set up automated accessibility tests on top of the interactions tests that we already had. And now we can use the auto accessibility to guide us and make better accessible components.

[07:32 - 07:47] And just keep in mind that X doesn't cover every single accessibility issue possible. For instance, there are some keyboard-related accessibility like tab bing and navigation that you should always check manually. And hopefully the combination of all of these tools are going to make you a better developer in the end. I'll see you in the next lesson.