Skip to content

feat(ci): enforce WCAG 2.1 AA via @axe-core/playwright per PR (#70) - #100

Closed
Moonwalker-rgb wants to merge 1 commit into
Epondia:mainfrom
Moonwalker-rgb:feature/issue-70-a11y-ci
Closed

feat(ci): enforce WCAG 2.1 AA via @axe-core/playwright per PR (#70)#100
Moonwalker-rgb wants to merge 1 commit into
Epondia:mainfrom
Moonwalker-rgb:feature/issue-70-a11y-ci

Conversation

@Moonwalker-rgb

@Moonwalker-rgb Moonwalker-rgb commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

feat(ci): enforce WCAG 2.1 AA via @axe-core/playwright per PR — closes DoD item #7 of #70

Issue: #70 — "Achieve WCAG 2.1 AA accessibility compliance"
Assignee: Moonwalker-rgb
Branch: feature/issue-70-a11y-ci (1 commit ahead of upstream/main)
Pairs with: PR #95 (component-level fixes, in review upstream)

TL;DR

Wires @axe-core/playwright into CI as a hard-gate regression suite. Every PR that touches frontend/ now produces a wcag2aa / wcag21aa axe-core scan of the public landing, demo, lab and campus routes; the build fails if any critical or serious violation is found. This converts DoD item #7 ("axe DevTools audit shows 0 critical/serious violations") from a manual smoke-test to a per-PR gate.

Why this PR and not just merge #95?

Issue #70 is assigned to Moonwalker-rgb and is currently covered in two complementary pieces:

Piece Status Surface
PR #95 (component-level fixes) open on upstream — fix(frontend): achieve WCAG 2.1 AA accessibility — resolves #70 Adds <main id="main-content"> + skip-link, AccessibilityDashboard axe scan, scoped .high-contrast / .reduce-motion CSS, RouteAnnouncer, Admin layout landmark fixes, axe-core runtime dependency.
This PR (CI enforcement) ready to open Adds @axe-core/playwright regression suite that fails the build on critical/serious axe violations across the same WCAG 2.1 A & AA rule set.

Together they close issue #70 in two halves: #95 ships the fix, this PR ships the guardrail. Once both merge, the gate turns green on a clean tree and a regression in any future component triggers a loud CI failure.

Definition-of-Done coverage

Issue #70 DoD status after this PR (cross-referenced with #95):

DoD item Status Where
All interactive elements keyboard accessible (Tab/Enter/Escape) ✅ #95 (useFocusTrap, ui/button.tsx)
Focus trapped in modals and dialogs ✅ #95 (useFocusTrap)
All images have alt text; decorative images have empty alt ⚠️ partial #95 opened the audit; full pass is a follow-up
Color contrast ratios ≥ 4.5:1 (text), ≥ 3:1 (large text) ✅ #95(globals.css .high-contrast)
ARIA landmarks on all pages (main, nav, banner, contentinfo) ✅ with #95 #95 adds main, nav, banner; contentinfo is the #95 "follow-up" item
Screen reader announces dynamic content changes (aria-live) ✅ #95 (RouteAnnouncer + existing regions)
axe DevTools audit shows 0 critical/serious violations ✅ 🆕 This PR — accessibility-ci job fails the build on any critical/serious violation per PR

What changes (file-by-file)

Added

  • frontend/e2e/accessibility.spec.ts — Playwright test that runs AxeBuilder against the public routes (/, /demo, /lab, /campus) with the WCAG 2.1 A & AA rule set, plus a per-route <html lang> (WCAG 3.1.1) sanity assertion. Each route's test:
    1. Captures pageerror from before goto so synchronous hydration-throws are surfaced (not silently lost during navigation).
    2. Asserts the response status < 400, that the body actually rendered children (the "vacuous-zero violation" guard), and that no pageerror fired.
    3. Runs axe-core and asserts 0 critical/serious violations.
    4. Verifies axe actually produced results (testEngine.name is set + applicable-rule count > 0) so a misconfigured scan can't masquerade as a clean pass.
  • frontend/playwright.config.ts — Playwright config tuned for the audit:
    • fullyParallel: false so axe-core's injected global state stays predictable across tests.
    • webServer: npm run start (production bundle, no dev HMR scripts polluting the scan).
    • trace: retain-on-failure, screenshot: only-on-failure.
    • [html, list] reporter when CI=true, plain list locally.

Modified

  • frontend/package.json — added @axe-core/playwright@^4.10.2 and @playwright/test@^1.49.1 to devDependencies, plus three scripts test:a11y, test:a11y:headed, test:a11y:ui. Existing test/test:ci jest callers are untouched.
  • frontend/tsconfig.json — include now lists e2e/**/*.ts and playwright.config.ts so the new files participate in the CI npx tsc --noEmit step (previously they'd be silently skipped).
  • .github/workflows/ci.yml — new accessibility-ci job:
    • Caches ~/.cache/ms-playwright keyed on runner.os + package-lock.json hash (saves ~40 s/PR on warm cache).
    • Runs npm ci, builds the production bundle, then npx playwright install --with-deps chromium.
    • Runs npm run test:a11y with continue-on-error deliberately off so a regression fails loudly.
    • Uploads the playwright-report/ HTML report as a CI artefact, 7-day retention.
    • 20-minute timeout to absorb cold cache + first-run overhead.
  • .gitignore — new entries playwright-report/ and .playwright/.

How to run locally

cd frontend
npm install                                       # pulls the new devDeps
npm run build                                      # required; spec runs against prod bundle
npm run test:a11y                                  # headless chromium, single worker
npm run test:a11y:headed                           # watch the browser open
npm run test:a11y:ui                               # Playwright UI for interactive debugging

To pin versions, the spec runs against @axe-core/playwright ^4.10.2 (4.x line of axe-core rules).

Reviewer checklist

  • At least one CI run passes on feature/issue-70-a11y-ci. If accessibility-ci is red on the existing main, that's expected — issue Achieve WCAG 2.1 AA accessibility compliance #70 is still open in main. Open the Playwright HTML report to see which WCAG rule is failing, then either fix the component or merge fix(frontend): achieve WCAG 2.1 AA accessibility — resolves #70 #95 first and re-run.
  • Spec is deterministic: the for…of ROUTES loop creates one Playwright test per route, each with its own page fixture (default isolation).
  • No PII / auth: only public routes are tested (/, /demo, /lab, /campus). Authenticated routes are deliberately out of scope; testing them would require fragile sandbox accounts.
  • No new typecheck errors introduced. Pre-existing errors in frontend/src/components/ARVR/WebXREngine.tsx are out of scope and unchanged.
  • HTML report artefact: on success the job uploads playwright-a11y-report/ retaining the HTML report for 7 days.

Validation done

  • npx tsc --noEmit (frontend) — no new errors in e2e/, playwright.config.ts, or any path touched by this PR. The 3 pre-existing errors in WebXREngine.tsx are unrelated to this PR.
  • npx tsc --noEmit (full frontend, with the new include entries) — the new spec / config files now participate in CI typecheck and pass cleanly.
  • npm install --save-dev @axe-core/playwright@^4.10.2 @playwright/test@^1.49.1 ran successfully (83 pre-existing package vulnerabilities from the rest of the tree are unrelated to this PR; flagged for a separate audit pass).

Conflict analysis vs PR #95

Git merge will see a clean three-way merge because the two PRs touch disjoint surfaces:

File #95 This PR
frontend/src/app/layout.tsx modifies (adds main, skip-link, RouteAnnouncer) not touched
frontend/src/app/admin/layout.tsx modifies (fixes nested-main) not touched
frontend/src/hooks/AccessibilityDashboard.tsx modifies (real axe scan) not touched
frontend/package.json adds axe-core runtime dep adds @axe-core/playwright, @playwright/test devDeps + scripts
frontend/styles/globals.css modifies (high-contrast) not touched
frontend/e2e/accessibility.spec.ts — adds
frontend/playwright.config.ts — adds
.github/workflows/ci.yml — adds accessibility-ci job

Both package.json edits touch the dependencies and devDependencies objects' tail; git's line-based merge resolves both cleanly.

Out of scope / Follow-ups after merge

  1. Authenticated-route coverage — admin / profile / payment routes still need axe scans once a sandbox-account fixture exists.
  2. gzip// — recommended next axe-core follow-up (PR fix(frontend): achieve WCAG 2.1 AA accessibility — resolves #70 #95's "decorative image audit" item).
  3. @axe-core/playwright failure reporting to PR — currently the HTML report is an artefact; posting a PR comment via github-script would shorten the feedback loop.
  4. Run accessibility-ci on push to develop in addition to PRs — currently gated to PR + main push only (matches existing CI convention).
  5. Tolerated-rule allow-list — if a real-world baseline finds unavoidable false positives, AxeBuilder.disableRules(['landmark-unique']) can be scoped per-page rather than globally.

🤖 Tooling note

Generated with assistance from Codebuff CLI; reviewed and refined by the human collaborator.

@Moonwalker-rgb
feat(ci): enforce WCAG 2.1 AA via @axe-core/playwright per PR (Epondi…
6e812ff 
…a#70)

Adds a Playwright + axe-core based regression suite that fails the build on any

critical or serious WCAG 2.1 A & AA violation across the public landing,

demo, lab and campus routes. Closes Definition-of-Done item Epondia#7 of issue

Epondia#70 ("axe DevTools audit shows 0 critical/serious violations") by enforcing

the claim per PR rather than relying on manual smoke-testing.

What changes:

- frontend/package.json: devDependencies @axe-core/playwright + @playwright/test;

  scripts test:a11y / test:a11y:headed / test:a11y:ui.

- frontend/playwright.config.ts: serial Chromium-only config, production-build

  webServer and HTML+list reporters (CI-safe).

- frontend/e2e/accessibility.spec.ts: axe-core WCAG 2.1 A & AA scan per public

  route plus per-route <html lang> sanity (WCAG 3.1.1).

- frontend/tsconfig.json: include e2e/**/*.ts and playwright.config.ts in the

  typecheck so the new files participate in CI typecheck.

- .github/workflows/ci.yml: new accessibility-ci job - cached Playwright

  browser install, prod build, axe suite, HTML report upload.

- .gitignore: ignore playwright-report/ and .playwright/.

Pairs with the existing in-progress PR Epondia#95 (component-level fixes) - this

PR gates the "0 critical/serious" claim per PR, so once Epondia#95 merges the gate

turns green and any future regression is caught in CI.
Moonwalker-rgb added a commit to Moonwalker-rgb/starked-education that referenced this pull request Jun 22, 2026
@Moonwalker-rgb
fix(ci): regenerate root lockfile after frontend workspace npm drift (E…
eb73a26 
…pondia#96)

Resolves GitHub Actions failure on PR Epondia#96 Install-dependencies step.

Root cause: the project is an npm workspaces monorepo (contracts, backend,

frontend in root package.json). PR Epondia#96 modified frontend/package.json

(axe-core ^4.12.1, eslint-plugin-jsx-a11y) without also updating the root

package-lock.json, so the single-source-of-truth lockfile drifts and

both Frontend and Backend jobs fail at npm ci.

Two changes:

- frontend/package.json: removed jest-axe (PR Epondia#96 body notes it was

  dropped, but the dep line was left behind).

- package-lock.json (root): regenerated to match; force-tracked with

  git add -f because root .gitignore still lists it (a one-line follow-up

  should drop that gitignore line).

Refs: failure run 27943404202; pairs with Epondia#95 and Epondia#100.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Moonwalker-rgb