Salesforce Accessibility Automation Libraries

Automated Accessibility Testing Libraries and Tools (@sa11y packages) based on [axe-core][axe] providing support for Jest unit tests, Vitest unit tests, WebdriverIO component/integration tests used by teams in Salesforce. However, they are not specific to Salesforce and can be used to test any UI supported by axe-core for accessibility. These libraries are designed to be flexible, customizable and reusable to support automated accessibility testing in different testing workflows from unit to integration tests.

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

• Docs
  • References
• Packages
  • Jest integration
  • Vitest integration
  • WDIO integration
  • assertAccessible API
  • a11y results formatter
  • Preset accessibility rules
  • Core accessibility matcher
  • Minified bundle for testing in browser
  • Internal packages
    • Test utilities
    • Integration Tests
    • Common utilities
  • Epilogue

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Docs

• Developer Guidelines
  • Refer to Quick start instructions to get started, if you are a developer looking to Contribute
• Code of Conduct
• Changelog
• LICENSE

References

• Automated Accessibility Tests with sa11y | Developer Quick Takes - YouTube
• Automated Accessibility Testing with sa11y | Salesforce Developers Blog
• Get Started with Web Accessibility | Salesforce Trailhead
• Accessibility Overview - Lightning Design System
• LWC Accessibility guide

Packages

This repo contains the following packages for automated accessibility testing:

Jest integration

• Provides a toBeAccessible() accessibility matcher for Jest
  • integrates the assertAccessible API with the Jest assertion API
• Provides an option to set up the sa11y API to be invoked automatically at the end of each test
• Includes custom results processors for enhanced test reporting and grouping violations by rule
• To add accessibility testing to your Jest tests use this package

Vitest integration

• Provides a toBeAccessible() accessibility matcher for Vitest
• Integrates the core accessibility checking logic with the Vitest testing framework
• Supports automatic checks and custom results processing for enhanced test reporting
• Built on the same core logic as the Jest integration via @sa11y/matcher
• To add accessibility testing to your Vitest tests use this package

WDIO integration

• Provides assertAccessible(), assertAccessibleSync() APIs that can be used with WebdriverIO to check accessibility of web pages rendered in browsers

assertAccessible API

• Checks DOM or HTML Element for accessibility issues and throws an error if a11y issues are found
• Supports both violations and incomplete results reporting
• To add accessibility testing to your Javascript unit tests not using Jest or Vitest, use this package

a11y results formatter

• Formats raw JSON output of a11y issues from [axe] into an easy to consume format by consolidating and cross-referencing
• Used by assert Accessible API and Jest/Vitest a11y matchers
• Provides exception list filtering and WCAG metadata enhancement
• To use axe directly and want to format the results from axe.run use this package
• A new formatter groupViolationResultsProcessor also made available to group the a11y violations per jest test case as the existing formatter would generate test failures for each violation

Preset accessibility rules

• Provides Base, Extended, Full accessibility preset rules as [axe] configuration
• The Base preset rule is used by default in the Jest/Vitest a11y matchers and assert Accessible APIs
  • The APIs can be overridden to use the Extended or Full ruleset as necessary
• Includes custom rule support and WCAG metadata for enhanced reporting

Core accessibility matcher

• Provides the core accessibility checking logic used by Jest and Vitest integrations
• Framework-agnostic programmatic APIs for accessibility testing
• Supports automatic checks, DOM mutation observation, and custom integrations
• Use this package directly for custom test runners or advanced scenarios requiring direct control

Minified bundle for testing in browser

• Provides a minified version of selected @sa11y libraries to be injected into a browser (using webdriver) and executed from integration testing workflows.
• Gives WCAG SC for rulesets in addition with [axe] tags
• Supports both Selenium Java and WebdriverIO integration patterns

Internal packages

Test utilities

• Private package providing test utilities, mock data, and common testing patterns for @sa11y packages
• Includes DOM fixtures with and without accessibility issues for testing

Integration Tests

• Private package providing integration tests for @sa11y packages across different environments
• Ensures cross-package compatibility and end-to-end functionality

Common utilities

• Common utilities, constants, error messages, and helper functions for @sa11y packages
• Provides shared functionality for environment detection, custom rules, and file processing

---

Epilogue

A wise person once said…

<!-- cSpell:disable -->

"Don't talk to me until I've had coffee and you've run axe"

![Embroidery that says "Don't talk to me until I've had coffee