sa11y

Salesforce Accessibility Automation Libraries

Automated Accessibility Testing Libraries and Tools (@sa11y packages) based on axe-core 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.

• Docs
  • References
• Canary releases
• 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

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](https://www.youtube.com/watch?v=ScqZisOBbUM&list=PLgIMQe2PKPSJdFGHjGpjd1FbCsOqq5H8t&index=21)

• [Automated Accessibility Testing with sa11y

  Salesforce Developers Blog](https://developer.salesforce.com/blogs/2020/10/automated-accessibility-testing-with-sa11y)

• [Get Started with Web Accessibility

  Salesforce Trailhead](https://trailhead.salesforce.com/en/content/learn/trails/get-started-with-web-accessibility)

• Accessibility Overview - Lightning Design System
• LWC Accessibility guide

Canary releases

To try changes from an open pull request before they are merged and released, e.g. to check a fix in your project, use a canary release: a test build of all public @sa11y/* packages published from the PR.

1. Comment canary on the PR. Only maintainers (people with write access to this repo) can trigger a canary, so ask one to do it if you can’t. PRs from forks are not supported.
2. CI tests the PR and publishes the packages to npm with the canary tag. Once they can be installed, usually within about 10 minutes, a bot replies on the PR with the version, e.g. 8.2.1-canary.57.1.gd39f94e.

3. Install that exact version in your project:

    yarn add -D @sa11y/jest@8.2.1-canary.57.1.gd39f94e
    # or
    npm install -D @sa11y/jest@8.2.1-canary.57.1.gd39f94e
   

   Use the same version for every @sa11y package your project depends on. The @sa11y packages they depend on are installed at that version too.

• Always pin the exact version. The canary tag moves to the newest canary from any PR, and ranges such as ^8.2.0 never pick up a canary.
• Canaries are for testing only. Switch back to a regular release once the change is merged and released.
• If npm fails with No matching version found for ... with a date before ..., your npm config blocks recently published versions. See Making a canary release for how to install a canary anyway, and for how maintainers can cut a canary from a branch without a PR.

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…

“Don’t talk to me until I’ve had coffee and you’ve run axe”

(Image courtesy: @shleewhite, @jorycunningham)

This site is open source. Improve this page.