Add automated a11y CI gate using jest-axe (WCAG 2.1 AA)

[mekarpeles]

Problem / Opportunity

Open Library has no automated accessibility (a11y) testing in CI. Accessibility regressions can land silently — a Lit component can ship with broken ARIA without any check failing. We have 17 open `Theme: Accessibility` issues and no tooling that would have caught them.

Opportunity: Wire jest-axe into the existing JavaScript test suite so that any PR introducing a WCAG 2.1 AA violation in a Lit component is blocked at CI.

Proposal

Add jest-axe as a devDependency and write WCAG 2.1 AA tests for the three Lit components that currently have manual ARIA attributes but no automated coverage:

• `openlibrary/components/OlPopover.js`
• `openlibrary/components/OlOptionsPopover.js`
• `openlibrary/components/OlToast.js`

Wire `npm run test:a11y` into `.github/workflows/javascript_tests.yml` so violations block merge.

This is Phase 1 of a broader a11y tooling plan. Phase 2 (Playwright + axe-core full-page scans) and Phase 3 (Lighthouse CI) are follow-on work.

Breakdown

• Install `jest-axe` as devDependency
• Write tests for `OlPopover`, `OlOptionsPopover`, `OlToast` (default + open states)
• Add `test:a11y` script to `package.json`
• Wire into `javascript_tests.yml` CI
• Verify all 477 existing tests still pass
• Verify 0 WCAG violations on current components

Success Criteria

• `npm run test:a11y` passes with 0 violations on merge
• CI blocks any future PR that introduces a new WCAG violation in a tested component
• All existing tests continue to pass

[rakshith1928]

I would like to take a look into this.

[openlibrary-bot]

Status

No blockers — this is ready to work on.

Context

• jest-axe is not yet a devDependency — confirmed in package.json and package-lock.json. The install step is a genuine first action.
• Jest's roots config doesn't include the Lit components directory. The Jest config in package.json currently covers openlibrary/plugins/openlibrary/js/ and tests/unit/js/ only. Test files placed in openlibrary/components/lit/__tests__/ won't be discovered. The existing precedent — tests/unit/js/OLMarkdownEditor.test.js imports from openlibrary/components/lit/html-block.js — suggests placing the a11y test files in tests/unit/js/ to avoid modifying roots. Alternatively, add openlibrary/components/lit to roots and create an __tests__ subdirectory there.
• javascript_tests.yml already runs npm run test, which resolves to npm run test:js && bundlesize → jest. Adding test:a11y as a distinct script and a separate - run: npm run test:a11y step in the workflow is the right approach — it keeps a11y failures isolated from the main test report.
• 17 open Theme: Accessibility issues are on record. The jest-axe gate targets only Lit components, not the broader template/HTML violations documented in those issues — the scope distinction is correct.

Issue Assessment

Action items

• Clarify test file location in the breakdown: tests/unit/js/ (matches existing OLMarkdownEditor pattern, no config change) vs. openlibrary/components/lit/__tests__/ (requires adding that path to roots in package.json). Either works — just needs a decision so contributors aren't guessing.

Full triage checklist (maintainers / Richy)

• Triage — correct labels applied
• Problem / opportunity — clearly stated with quantification (17 open a11y issues, no CI gate)
• Scope — tightly scoped to three named components; Phase 2/3 explicitly deferred
• Justification — silent regressions are a real cost; rationale is sufficient
• Success & testing criteria — 0 violations on merge, CI blocks new violations, existing tests unaffected
• Proposal & breakdown — concrete checklist with 6 steps; one ambiguity (test file location) noted above
• If bug: environment & repro steps — N/A (feature request)
• Risks, concerns, open questions — none present; jsdom + custom elements is a known jest-axe constraint worth watching but not blocking
• Richy context — Jest config, existing test patterns, and javascript_tests.yml reviewed
• References — jest-axe linked

Note

This comment was automatically generated by Richy, via PAM, Open Library's Project AI Manager, on behalf of @mekarpeles. Richy is designed to provide status visibility, perform basic project management functions and relevant codebase research, and provide actionable feedback so contributors aren't left waiting.