/experience-lwc-accessibility-jest-run

name: experience-lwc-accessibility-jest-run
description: "Use ALWAYS when running Sa11y accessibility Jest tests for an LWC — locally before pushing, producing the command(s), running one file vs a suite, selecting tests by naming convention, saving Sa11y-rendered HTML, or reproducing a Sa11y/A11yBug failure. Covers core (Bazel; `bazel test //<module>:<target>`) and standalone `npx jest` (`.accessibility.test.js`, `@sa11y/jest`). REQUIRED for a `run-plan.md`, a failing a11y test's exit code, or `SA11Y_*`/`A11yBug`/core-Bazel test paths. DO NOT TRIGGER for functional Jest tests, a11y review without running tests (use experience-accessibility-validate), or Selenium-based a11y tests."
metadata:
  version: "1.0"
  domains: ["Experience"]
  relatedSkills:
    - "experience-accessibility-validate"
  cliTools:
    - tool: ["node"]
      semver: ">=18.0.0"
    - tool: ["npm"]
      semver: ">=8.0"

<!-- a11y-expert-managed-skill -->

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

c