vitest-accessibility-checker weekly downloads statistics

vitest-accessibility-checker

⚠️ Important: This package requires Vitest Browser Mode

Accessibility testing plugin for Vitest that integrates IBM Equal Access Accessibility Checker. This package is designed specifically for Vitest Browser Mode and requires a real browser environment to run accessibility scans.

Requirements

• Vitest 2.0+ with Browser Mode enabled • A browser provider (Playwright, WebdriverIO, or Puppeteer) • Node.js 16 or higher

Installation

Optional: XLSX Report Format

If you want to generate reports in XLSX format, you need to install exceljs as an additional dependency:

Without exceljs installed, all other report formats (JSON, HTML, CSV) will work normally, but XLSX format will be disabled with a warning message.

Usage

1. Configure Vitest with Browser Mode

Browser Mode is required. Add the plugin to your vitest.config.js and ensure browser mode is enabled:

2. Setup Custom Matcher (Optional but Recommended)

Create a setup file to extend Vitest's expect with the toBeAccessible matcher:

Add it to your vitest config:

3. Write Tests

Using the Custom Matcher (Recommended)

The toBeAccessible matcher provides the cleanest syntax:

Using Direct API Calls

You can also use the API functions directly:

Testing with Inline HTML

You can also test accessibility by rendering HTML directly:

API

Custom Matcher

expect(element).toBeAccessible(label)

Custom Vitest matcher that scans an element and asserts it has no accessibility violations.

• element: DOM element or document to scan • label: String label for this scan • Throws: Assertion error if violations found • Returns: Promise

Example:

Direct API Functions

All functions can be imported from vitest-accessibility-checker/commands:

getCompliance(content, label)

Scans the provided content and returns a compliance report.

• content: DOM element or document to scan • label: String label for this scan • Returns: Promise - Accessibility report with results array

Example:

assertCompliance(report)

Checks a report and returns a status code based on violations and baseline comparison.

• report: Report object from getCompliance • Returns: Promise - 0 if passes, 1 if fails baseline, 2 if fails on failLevels

Example:

getBaseline(label)

Gets the baseline for a specific label.

• label: String label for the baseline • Returns: Promise - Baseline data

getDiffResults(label, actual)

Gets diff results between current scan and baseline.

• label: String label for comparison • actual: Current report object • Returns: Promise - Array of diff objects with 'kind' property

getConfig()

Gets the current accessibility checker configuration.

• Returns: Promise - Configuration object

stringifyResults(report)

Converts a report to a formatted string for display.

• report: Report object • Returns: String - Formatted report string

Configuration

Create an .achecker.yml or achecker.js file in your project root:

If your project uses ES modules ("type": "module" in package.json), Node.js cannot load a CommonJS achecker.js file. Use an achecker.mjs file with a default export instead:

Reports

Reports are generated in the results folder (configurable) with: • JSON reports for each scan • HTML summary report • Baseline comparison (if enabled)

License

Apache-2.0 - See LICENSE in the equal-access repository

Description from the npm listing.