Shift Left on Accessibility with Vitest Browser Mode

When software engineers run accessibility testing, it is often done late in the development cycle leading to rushed fixes. Instead, developers can use Vitest Browser Mode (with helpful plugins) to move accessibility testing earlier in the process. In the long run, this will save developers time and make their applications more accessible to all users.

Getting Started

With website accessibility becoming increasingly required by regulation, developers who previously ignored accessibility are now learning about it. For developers who are new to accessibility testing, they often begin with an automated checker such as axe DevTools or the IBM Equal Access Accessibility Checker. While I could complain about how developers stop after using a tool… I will just mention that accessibility testing is not done until someone manually tests a web application without a keyboard (the most common accessibility need) and with a screen reader. Usability testing cannot be fully automated, but automated checkers will catch the most common issues.

Limitations of E2E Accessibility Testing

While software developers begin by running automated checkers once in their own browser, any who are regularly deploying software will want to automate the runs. The most common place to run automated checkers is in E2E tests using tools like Playwright or Cypress. This makes sense: those are the full pages that users will interact with, so an accessibility check there will cover everything that users see. However, there are limitations to an E2E test:

• For highly interactive web applications, it is hard to cover all the states that a UI will enter in E2E tests. Error states are especially challenging.
• E2E tests are only run when the application is fully built and it is more expensive to do rework to fix the bugs. AI coding assistants won’t be able to get feedback from the tests unless you can run everything locally.
• Some testing tools do not scan into iframes, so if you use iframes, the content inside will not be checked and bugs will be missed.

Better Testing with Component Accessibility Testing

Wouldn’t it be nice if we could catch those bugs earlier before everything is integrated? And wouldn’t it be even better if your AI coding assistant could just do the testing during development? With Vitest Browser Mode, both of those can happen!

Get Samuel Meyer’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

Vitest Browser Mode extends the well-known Vitest testing framework and run tests in an actual browser. Unlike running in JSDom as Vitest would before, CSS and SVG’s will render exactly as they will in a browser, so you can scan a single UI component for accessibility failures and catch issues like insufficient contrast. Vitest Browser Mode documentation already encourages developers to use the accessible name of elements as a starting accessibility check, but you can run a full scan with vitest-accessibility-checker. It runs the checks from the IBM Equal Access Accessibility Checker on a single component at a time. React is the default for examples, but all major frameworks are supported.

Component Accessibility Test Example

Below is an example test where you can see how easy it is to integrate into your tests. The toBeAccessible method is added by vitest-accessibility-checker.

import { expect, test } from 'vitest';
import { render } from 'vitest-browser-react';
import HelloWorld from './HelloWorld.jsx';

test('renders name', async () => {
  const { getByText } = await render(<HelloWorld name="Vitest" />);
  await expect.element(getByText('Hello Vitest!')).toBeInTheDocument();
  await expect(document.body).toBeAccessible();
});

A full example with everything you will need to get started is available at https://github.com/samueldmeyer/vitest-accessibility-checker

A sample test failure after catching insufficient contrast

Common Issues

One issue crops up for every new developer using vitest-accessibility-checker: most components are expected to be loaded inside a `<main>` block, so developers end up wrapping most renders with `<main>…</main>` to avoid accessibility failures about missing landmarks.

For those setting up Vitest Browser Mode up for the first time, running a browser on the CI server can be a new experience. I recommend using the Playwright images provided by Microsoft if you are unsure how to get headless Chrome (or other browsers) running in a way that will let Vitest browser mode run on every pull request.

Go Try It

Vitest Browser Mode allows developers to shift accessibility testing left from E2E tests to components tests. As a result, accessibility issues can be found before code is merged.

If you are already using Vitest Browser Mode, try adding accessibility tests there. If not, try Vitest Browser Mode and enjoy seeing your components tested exactly the way they will be used. Then add accessibility testing so your users will never have to deal with accessibility bugs.

The postings on this site are my own and don’t necessarily represent IBM’s positions, strategies or opinions.