jest-aria-snapshots

A custom Jest snapshot serializer for testing accessibility with Testing Library. Converts DOM elements into clean, readable accessibility tree snapshots focusing on ARIA roles, names, and attributes.

Installation

yarn add -D jest-aria-snapshots

Development

# Install dependencies
yarn install

# Build the project
yarn build

# Watch mode
yarn dev

# Run tests
yarn test

# Watch tests
yarn test:watch

# Clean build artifacts
yarn clean

Usage

With Testing Library

This serializer is designed to work seamlessly with Testing Library's DOM queries:

/**
 * @jest-environment jsdom
 */
import { render, screen } from '@testing-library/react';
import { ariaSnapshotSerializer } from 'jest-aria-snapshots';

// Add the serializer
expect.addSnapshotSerializer(ariaSnapshotSerializer);

test('navigation accessibility', () => {
  render(
    <nav aria-label="Main navigation">
      <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About</a></li>
      </ul>
    </nav>
  );

  const nav = screen.getByRole('navigation');
  expect(nav).toMatchSnapshot();
});

Snapshot output:

{
  "aria-label": "Main navigation",
  "children": [
    {
      "children": [
        {
          "children": [
            {
              "name": "Home",
              "role": "link",
              "text": "Home"
            },
          ],
          "role": "listitem"
        },
        {
          "children": [
            {
              "name": "About",
              "role": "link",
              "text": "About"
            },
          ],
          "role": "listitem"
        },
      ],
      "role": "list"
    },
  ],
  "name": "Main navigation",
  "role": "navigation"
}

Global Configuration

Add it globally in your jest.config.js:

export default {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
};

In jest.setup.js:

import { ariaSnapshotSerializer } from 'jest-aria-snapshots';
import '@testing-library/jest-dom';

expect.addSnapshotSerializer(ariaSnapshotSerializer);

Custom Matcher

Prefer an explicit matcher instead of registering a serializer? Extend Jest with toMatchAriaSnapshot and call it directly inside your tests:

import { render, screen } from '@testing-library/react';
import { toMatchAriaSnapshot } from 'jest-aria-snapshots';

expect.extend({ toMatchAriaSnapshot });

test('button accessibility', () => {
  render(<button aria-label="Close dialog">✕</button>);

  // Basic usage
  expect(screen.getByRole('button')).toMatchAriaSnapshot();

  // Per-call options
  expect(screen.getByRole('button')).toMatchAriaSnapshot({
    includeTextNodes: false,
  });
});

Create reusable matcher variants with predefined options via createAriaSnapshotMatcher:

import {
  toMatchAriaSnapshot,
  createAriaSnapshotMatcher,
} from 'jest-aria-snapshots';

const toMatchAriaSnapshotWithoutText = createAriaSnapshotMatcher({
  includeTextNodes: false,
});

expect.extend({
  toMatchAriaSnapshot,
  toMatchAriaSnapshotWithoutText,
});

expect(screen.getByRole('navigation')).toMatchAriaSnapshotWithoutText();

The matcher uses the same formatting logic as the serializer, so existing snapshots remain compatible whether you prefer expect.addSnapshotSerializer() or expect.extend().

What Gets Captured

The serializer extracts and formats:

From DOM Elements:

• ✅ Implicit ARIA roles (button, link, navigation, etc.)
• ✅ Explicit role attributes
• ✅ Accessible names (from aria-label, aria-labelledby, labels, text content)
• ✅ Accessible descriptions (from aria-describedby)
• ✅ All aria-* attributes
• ✅ State properties (checked, disabled)
• ✅ Child elements with roles (nested accessibility tree)

From Plain Objects:

• ✅ Objects with role, name, or description properties
• ✅ Objects with aria-* attributes

Examples

Button with aria-label

const button = screen.getByRole('button', { name: /close/i });
expect(button).toMatchSnapshot();
// {
//   "aria-label": "Close dialog",
//   "name": "Close dialog",
//   "role": "button",
// }

Form with inputs

const form = screen.getByRole('form');
expect(form).toMatchSnapshot();
// {
//   "children": [
//     {
//       "name": "Email",
//       "role": "textbox",
//     },
//   ],
//   "role": "form"
// }

Checkbox state

const checkbox = screen.getByRole('checkbox');
expect(checkbox).toMatchSnapshot();
// {
//   "checked": true,
//   "name": "I agree to the terms",
//   "role": "checkbox",
// }

Why Use This?

Traditional DOM snapshots can be noisy and fragile. This serializer focuses on the accessibility tree - what actually matters for users with assistive technology. It helps you:

• 🎯 Test the user experience, not implementation details
• 📸 Create focused snapshots that highlight accessibility
• 🔍 Catch accessibility regressions early
• 📚 Document component accessibility in your tests