Running LWC Accessibility Jest Tests
Run Sa11y accessibility unit tests on Lightning Web Components in either:
- Core (Bazel) — when a
WORKSPACEfile 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
WORKSPACEfile is present). - For standalone Jest tests:
@sa11y/jestinstalled 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:
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:
Component tests typically live under
modules/{componentDir}/{componentName}/__tests__/.
Prefer a single-file target when the failing test path is known:
Run all Sa11y Jest tests in a module when a specific test is not known:
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.
Or target a specific file:
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:
0means all tests passed,3means tests failed, and1means the build or command failed. - Jest:
0means all tests passed and1means 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.jsextension 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/jestdependency, andjsdomenvironment.
