sa11y

@sa11y/vitest

`@sa11y/vitest`

Accessibility matcher for Vitest

Overview

The toBeAccessible() API from this library can be used in Vitest unit tests to test HTML elements or DOM for accessibility.

Note: The core accessibility logic is provided by @sa11y/matcher, which can be used directly for custom or framework-agnostic testing.

Install

Using yarn: yarn add -D @sa11y/vitest
Using npm: npm install -D @sa11y/vitest

Setup

The accessibility APIs need to be registered with Vitest before they can be used in tests.

Project level

You can set up the Sa11y API once at the project level to make it available to all the Vitest tests in the project.

Add a Vitest setup file (e.g. vitest-setup.ts) and add the following code to register the Sa11y matcher:

import { setup } from '@sa11y/vitest';
// Register the Sa11y matcher with default options
setup();

// Register with custom options for automatic checks and DOM saving
setup({
    autoCheckOpts: { runAfterEach: true, cleanupAfterEach: true },
    renderedDOMSaveOpts: {
        /* your RenderedDOMSaveOpts here */
    },
});

In your vitest.config.ts, add the setup file to the setupFiles array:

import { defineConfig } from 'vitest/config';

export default defineConfig({
    test: {
        setupFiles: ['./vitest-setup.ts'],
    },
});

This makes the toBeAccessible API available for any test in the project.

Test module level

You can also invoke setup before using the toBeAccessible API in individual test modules:

import { setup } from '@sa11y/vitest';

beforeAll(() => {
    setup();
});

This makes the toBeAccessible API available for the tests only in that specific test module.

Usage

toBeAccessible can be invoked on the entire document (JSDOM) or on a specific HTML element to check for accessibility:

import { setup } from '@sa11y/vitest';
import { extended, full } from '@sa11y/preset-rules';

beforeAll(() => {
    setup();
});

it('should be accessible', async () => {
    // Setup DOM to be tested for accessibility
    // ...

    // Assert that DOM is accessible (using base preset-rule)
    await expect(document).toBeAccessible();

    // Can be used to test accessibility of a specific HTML element
    const elem = document.getElementById('foo');
    await expect(elem).toBeAccessible();

    // To test using an extended ruleset with best practices and experimental rules
    await expect(document).toBeAccessible(extended);

    // To test using all rules provided by axe
    await expect(document).toBeAccessible(full);
});

Caveats

Async: toBeAccessible must be invoked with async/await or Promise.
Fake Timers: When timers are mocked (e.g. with Vitest’s fake timers), the accessibility API can timeout. Switch to real timers before invoking the accessibility API.
DOM: Accessibility checks require a rendered DOM (e.g., JSDOM or a real browser environment).
template: <template> elements are not rendered in DOM and hence cannot be checked directly without rendering.

Automatic checks

The Sa11y Vitest API can be set up to be automatically invoked at the end of each test as an alternative to adding the toBeAccessible API at the end of each test.

When automatic checks are enabled, each child element in the DOM body will be checked for accessibility and failures reported as part of the test.

import { setup } from '@sa11y/vitest';

setup({ autoCheckOpts: { runAfterEach: true } });

// To optionally clean up the body after running accessibility checks
setup({ autoCheckOpts: { runAfterEach: true, cleanupAfterEach: true } });

// To customize how/where the rendered DOM is saved during automatic checks
setup({
    autoCheckOpts: { runAfterEach: true },
    renderedDOMSaveOpts: {
        /* your RenderedDOMSaveOpts here */
    },
});

Options

autoCheckOpts: Options for automatic accessibility checks (see below)
renderedDOMSaveOpts: Options for saving the rendered DOM during automatic checks. Allows customizing how and where the DOM is saved for debugging or reporting purposes. See @sa11y/matcher RenderedDOMSaveOpts for details.

autoCheckOpts:

runAfterEach: Run after each test (for integration with test runners)
cleanupAfterEach: Clean up the DOM after checking
consolidateResults: Deduplicate results
filesFilter: Array of file path substrings to skip automatic checks for
runDOMMutationObserver: Enable DOM mutation observer mode
enableIncompleteResults: Include incomplete results

Results Processor

A custom results processor is available for transforming accessibility errors in Vitest test results.
See the API: vitestResultsProcessor.

@sa11y/matcher: Provides the core accessibility checking APIs used by this package. Use it directly for custom test runners or advanced integrations.

This site is open source. Improve this page.