Accessibility Tree Snapshots in Pleasantest

Written by Caleb Eby on

Illustration by Danielle Romo

We’re thrilled to announce that we’ve added accessibility tree snapshots to Pleasantest. These snapshots incorporate important accessibility details into your tests, helping you to understand, track, and maintain the accessibility of your interfaces. We believe Pleasantest is the first testing tool to provide this incredibly useful feature.

How it works

The accessibility tree snapshots feature combines snapshot testing with an accessibility tree similar to the one that appears in Chrome or Firefox devtools.

At various points throughout your Pleasantest test, you can write:

expect(await getAccessibilityTree(element)).toMatchInlineSnapshot();

Then, when you first run your test, Jest will fill automatically fill in the toMatchInlineSnapshot() call with a representation of the accessibility tree for the element you passed in:

expect(await getAccessibilityTree(accountForm)).toMatchInlineSnapshot(`
  form "Edit Account Information"
    heading "Edit Account Information"
      text "Edit Account Information"
    text "First Name"
    textbox "First Name"
    text "Last Name"
    textbox "Last Name"
`);

After this, whenever you run your tests, Jest will compare the current accessibility tree with the accessibility tree saved in the snapshot. If there are any changes, the test will fail and Jest will show you the changes.

If the changes to the accessibility tree were intentional, you can approve the changes by passing the -u flag to Jest or by pressing u in watch mode. Then Jest will replace the saved inline snapshots with the updated accessibility tree.

Why not use queries and assertions?

Everything that can be tested with getAccessibilityTree can also be tested manually using queries and assertions. For example, the above accessibility snapshot can be tested using:

await expect(accountForm).toHaveRole("form");
await expect(accountForm).toHaveAccessibleName("Edit Account Information");
within(accountForm).getByLabelText("First Name");
within(accountForm).getByLabelText("Last Name");
await within(accountForm).queryByRole("heading", { name: "Edit Account Information" });

There’s nothing wrong with this approach, but it is more cumbersome and time-consuming. These manual assertions don’t test that each of the children is a direct child of the form in the accessibility tree. Nor do they test that there are no additional children of the form. While you could write more assertions to test those, Pleasantest’s getAccessibilityTree snapshot does it automatically.

In addition, accessibility tree snapshots make it very easy to quickly test a lot of things about an interface, while providing an easy-to-skim representation of the structure of UI. The accessibility tree snapshot makes it much easier to visualize structure and relationships between elements than a sequence of assertions does.

As the UI being tested changes over time, Jest will show the changes to the accessibility tree, and give the test author the opportunity to automatically update the saved accessibility tree snapshot. Then, the changes to the accessibility structure will be easily visible to reviewers through the git diff as well.

Of course, sometimes there are still benefits to zooming in to a single element and making more specific assertions about the element, and in those cases, manually-written assertions are more useful than getAccessibilityTree. Accessibility tree snapshots are just an additional tool we can use to test our websites and apps.

Example

I’ve written an example set of tests using getAccessibilityTree with comments throughout which explain what the different parts of the test are doing. There’s also documentation available for getAccessibilityTree in the Pleasantest repo.

Try it out!

Automated testing tools can’t catch every issue, so it’s important to manually test interfaces with assistive technologies, but we’re excited to share an additional tool to help build and maintain accessible interfaces. We hope you find it useful. Let us know if you run into any issues or have ideas for how to improve it.

Caleb Eby

Caleb Eby is a developer passionate about web performance, efficient JavaScript, and helpful web tooling. You can find his abandoned side-projects on GitHub

Never miss an article!

Get Weekly Digests


Leave a Comment

Please be kind, courteous and constructive. You may use simple HTML or Markdown in your comments. All fields are required.


Let’s discuss your project! Email Us