Running LWC Accessibility Jest Tests

Run Sa11y accessibility unit tests on Lightning Web Components in either:

• Core (Bazel) — when a WORKSPACE file is present.
• Standalone (Jest) — when there's no WORKSPACE.

Selenium-level reproductions, GUS A11yBug ingestion, and other internal Salesforce-only flows are out of scope for this skill. For source-code-level WCAG review without running tests, see experience-accessibility-validate.

When to Use This Skill

• User wants to run accessibility unit tests (Sa11y Jest) locally before pushing a fix.
• User has a known failing test file path (e.g. from an A11yBug's Test_Names__c) and wants to target it directly.
• User is iterating on an accessibility fix and needs the fastest pass/fail signal.

Prerequisites

• For Bazel Jest tests: a Salesforce core build environment (a WORKSPACE file is present).
• For standalone Jest tests: @sa11y/jest installed and configured.

Workflow

Choose the approach based on the environment. If this is not a Salesforce core build environment, do not mention the Core workflow.

Core (Bazel)

Use this mode when a WORKSPACE file is present. The base command is:

{coreRootPath}/tools/bazel test [TARGET] --test_output=streamed --test_env=SA11Y_AUTO=1 --test_env=SA11Y_ENABLE_DOM_MUTATION_OBSERVER=1

Replace {coreRootPath} with the Core repository root, {moduleName} with the module name, and {relativePath} with the test file path without the .test.js extension.

To discover targets and paths:

find {coreRootPath}/{moduleName} -name "*.test.js" -type f
{coreRootPath}/tools/bazel query "tests(//{moduleName}:*)"

Component tests typically live under modules/{componentDir}/{componentName}/__tests__/.

Prefer a single-file target when the failing test path is known:

{coreRootPath}/tools/bazel test //{moduleName}:{relativePath} --test_output=streamed --test_env=SA11Y_AUTO=1 --test_env=SA11Y_ENABLE_DOM_MUTATION_OBSERVER=1

Run all Sa11y Jest tests in a module when a specific test is not known:

{coreRootPath}/tools/bazel test //{moduleName}:sa11y_jest_test --test_output=streamed --test_env=SA11Y_AUTO=1 --test_env=SA11Y_ENABLE_DOM_MUTATION_OBSERVER=1

Multiple module targets can be passed to the same command. To filter tests within a module, add --test_arg=--testMatch="**/{modulePath}/**".

Useful options:

• Update snapshots: --test_arg="--updateSnapshot"
• Disable cached test results: --cache_test_results=no
• Save rendered HTML: --test_env=SA11Y_ENABLE_RENDERED_DOM_SAVE=1 --test_env=SA11Y_RENDERED_DOM_SAVE_PATH=sfdc-test/unit/javascript/htdocs/sa11y/jest

Use sfdc-test/unit/javascript/htdocs/sa11y/jest as the rendered DOM save path to avoid EPERM errors.

Standalone (Jest)

Use this mode when no WORKSPACE file is present. Run all accessibility tests:

Do not prepend SA11Y_* environment variables in standalone mode; @sa11y/jest is activated through the project's Jest setup.

npm test -- --testMatch="**/*.accessibility.test.js"

Or target a specific file:

npm test -- src/components/MyComponent/__tests__/MyComponent.accessibility.test.js

Use the filename or path supplied by the user. When the named test is in the current directory, keep a bare filename bare instead of inventing a path.

Other useful options are --coverage, --updateSnapshot, --watch, and --verbose. To target a named test, use npm test -- --testNamePattern="MyComponent accessibility".

Ensure Jest uses a jsdom environment and loads the project's @sa11y/jest setup file. Copy or adapt the bundled assets/jest.config.js template into the project's Jest configuration, and copy assets/sa11y-jest-setup.js to test/setup/sa11y-setup.js. If the project already has a Jest configuration, merge the relevant settings instead of overwriting unrelated configuration.

The SA11Y_* variables shown above are for Core/Bazel only; the Bazel commands already include them.

Response Scope

Answer only what the user asked. Emit the requested command or commands plus the relevant exit-code meaning. Do not add watch, coverage, snapshot-update, HTML-save, or other variants unless the user requests them.

Expected Exit Codes

• Bazel: 0 means all tests passed, 3 means tests failed, and 1 means the build or command failed.
• Jest: 0 means all tests passed and 1 means tests failed or an error occurred.

Verification Checklist

• Sa11y Jest run completed with a clear pass/fail signal (exit 0 or 3 for Bazel; exit 0 or 1 for Jest).
• If snapshots were intentionally updated, the new snapshots are committed alongside the fix.

Troubleshooting

• Bazel test "not found" — the target path is off. Remember to drop the .test.js extension in {relativePath}.
• HTML saving fails with EPERM — use the prescribed save path sfdc-test/unit/javascript/htdocs/sa11y/jest.
• Standalone tests do not run — verify the test naming pattern, Jest configuration, @sa11y/jest dependency, and jsdom environment.