This document tracks the rollout of @axe-core/playwright across every
Playwright suite in the monorepo so that, per V1-P2-3500's verification text,
"each spec ends with await axe(page).analyze() returning zero serious or
critical violations." The "returning zero" half is the per-surface verification
work in V1-P2-3510..3519; this task owns the tooling.
Foundation#
Landed by 2026-05-05 (feat(shared): add shared playwright a11y helper, commit
e1613e9660):
- pnpm-workspace.yaml: catalog entries
axe-core: ^4.11.0and@axe-core/playwright: ^4.11.0(matching the major in use today across apps/lilith/web, apps/oshun/{web,admin}, apps/kalika/web). libs/shared/testing/src/playwright/: shared helper module exposinganalyzeA11y(page, options)— raw axe resultsexpectNoSeriousA11yViolations(page, options)— assert helper that fails on serious + critical impacts (configurable viafailOn)filterFailingViolations/formatA11yViolations— used both by the assert helper and by external consumersextendWithA11y(test)— Playwrighttest.extendaddingskipAxe+axeOptionsper-test fixturesaxeAfterEach(test)— one-line entry point: returns an extendedtestwhoseafterEachruns axe automatically (skips if test failed/timed-out, or page is closed). The auto-fixture pattern satisfies V1-P2-3500's "each spec ends with axe.analyze()" without spec-by-spec edits.
- tsconfig.base.json:
@oshun/testing/playwrightpath mapping. - package.json (
@oshun/testing):./playwrightexport with axe- Playwright as optional peer deps (non-e2e consumers don't pay the bundle cost).
Per-suite wiring status#
| Suite | Status | Notes |
|---|---|---|
testing/e2e |
wired | fixtures.ts + base.page.ts uses expectNoSeriousA11yViolations |
apps/bellona/control-room |
wired | e2e/fixtures.ts |
apps/yemaya/studio-web |
wired | e2e/fixtures.ts |
apps/tara/web |
wired | e2e/fixtures.ts + tsconfig now includes e2e/**/*.ts |
apps/metis/admin |
wired | e2e/fixtures.ts + package.json now declares @playwright/test |
apps/sophia/workbench |
wired | e2e/fixtures.ts + tsconfig now includes e2e/**/*.ts |
apps/hestia/web |
wired | e2e/fixtures.ts |
apps/demeter/web |
wired | e2e/fixtures.ts |
apps/oshun/web |
wired | e2e/fixtures.ts (already had axe locally) |
apps/oshun/admin |
wired | e2e/fixtures.ts (already had axe locally) |
apps/kalika/web |
wired | e2e/fixtures.ts (already had axe + pa11y locally) |
apps/metis/web |
wired | e2e/fixtures.ts + package.json now declares axe deps |
serwaa/services/admin-dashboard |
deferred | Separate-repo conventions (see serwaa/CLAUDE.md); rollout there is owned by the serwaa team. |
apps/lakshmi/browser-extension |
deferred | JS-based browser-extension Playwright suite; popup.spec.js runs against the rendered popup but the catalog/Worktrees pattern requires the suite migrate to TS first. |
apps/psyche/admin |
deferred | Suite is currently visual-snapshot only (tests/visual/auth-signin.spec.ts); axe analysis adds no signal until interactive flows land. |
libs/nous/video-removal |
deferred | The lone .pw.spec.ts is human-evaluation-pipeline.pw.spec.ts — a non-UI evaluation harness. axe is irrelevant here. |
Wired suites accept three usage patterns:
- Auto-fixture (preferred for new specs):ts
import { test, expect } from '../fixtures'; test('login flow', async ({ page }) => { await page.goto('/'); // axe runs automatically at end of test }); - Explicit per-spec call:ts
import { test, expect } from '@playwright/test'; import { expectNoSeriousA11yViolations } from '@oshun/testing/playwright'; test('login flow', async ({ page }) => { await page.goto('/'); await expectNoSeriousA11yViolations(page); }); - Page-object helper:
BasePage.checkAccessibility()(intesting/e2e/page-objects/base.page.ts) wraps the explicit call — page objects in the central e2e suite can invokeawait this.checkAccessibility()at any point in a flow.
Existing-spec migration (complete — 2026-05-05)#
Every wired suite's *.spec.ts files now import test and expect from the
suite's local fixtures.ts. The migration was a one-line change per spec
(scripts-equivalent: python3 /tmp/migrate-spec-imports.py):
- import { test, expect } from '@playwright/test';
+ import { test, expect } from './fixtures';
Specs that previously destructured types in the same line
(import { expect, test, type Page } from '@playwright/test') were split into a
runtime import from ./fixtures and a separate
import type { Page } from '@playwright/test' so type-only references kept
resolving to the upstream Playwright types. Per-suite landings:
| Suite | Specs migrated | Commit batch |
|---|---|---|
apps/bellona/control-room |
1 | chore(bellona): wire control-room… |
apps/kalika/web |
3 | chore(kalika): wire web… |
apps/tara/web |
6 | chore(tara): wire web… |
apps/hestia/web |
8 | chore(hestia): wire web… |
apps/demeter/web |
10 | chore(demeter): wire web… |
apps/metis/web |
12 | chore(metis): wire web… |
apps/metis/admin |
15 | chore(metis): wire admin… |
apps/oshun/admin |
55 | chore(oshun): wire admin… |
apps/oshun/web |
560 | chore(oshun): wire web… batch 1..5/5 |
apps/yemaya/studio-web |
1 | chore(yemaya): wire studio-web… |
apps/sophia/workbench |
1 | chore(sophia): wire workbench… |
| Total | 672 |
Two app tsconfigs (apps/yemaya/studio-web, apps/sophia/workbench) declared
"rootDir": ".", which made TypeScript reject fixtures.ts's import of
@oshun/testing/playwright with TS6059 even after the path mapping was added.
Dropping the explicit rootDir (TS infers from include) resolved the gate
without changing the emit shape — these projects build via Vite/Playwright, not
tsc, so the inferred root is the correct surface anyway.
Each per-app tsconfig got an explicit paths entry pointing
@oshun/testing/playwright at
../../../libs/shared/testing/src/playwright/index.ts. The base tsconfig
already had the mapping but flat-file paths overrides at the per-app level
fully replace the inherited block, so the helper would otherwise resolve as
any and silently disable the auto-fixture's typing.
CI enforcement (complete — 2026-05-05)#
eslint.config.js carves apps/<domain>/<app>/e2e/**/*.spec.ts out of the
global spec-ignore (vitest specs in src/, test/, tests/, and __tests__/
remain ignored — they are not parseable by the projectService config) and
applies a scoped no-restricted-imports rule that fails when a spec imports
test or expect directly from @playwright/test. The rule message points
contributors at the suite's ./fixtures (or ../fixtures).
import type { Page } from '@playwright/test' is explicitly allowed via the
rule's importNames carve-out so type references keep resolving upstream.
The rule was verified against:
- A migrated spec (
import { test, expect } from './fixtures') — passes. - A regressed spec (
import { test, expect } from '@playwright/test') — two errors, one per restricted import name. - A type-only sibling import (
import type { Page } from '@playwright/test') — passes (type imports skipno-restricted-imports'simportNamescheck). - Non-spec source files (
apps/oshun/web/src/app/page.tsx,libs/shared/testing/src/playwright/axe.ts) — silent (rule scoped to e2e/**/*.spec.ts only).
Test it#
The auto-fixture is exercised end-to-end by the accessibility-audit spec in
apps/kalika/web/e2e/ (which already calls expectNoWcag21AaViolations) and by
assistant-accessibility.spec.ts in apps/oshun/web/e2e/. Both pass against
the current main and demonstrate that the helper's filter/format paths work as
documented.
V1-P2-3500 status#
All three completion gates have landed:
- ✅ Every spec in every wired suite imports
testfrom itsfixtures.ts(672 specs across 11 app suites). - ✅ The four deferred suites have an explicit verdict
(
serwaa/services/admin-dashboard,apps/lakshmi/browser-extension,apps/psyche/admin,libs/nous/video-removal— recorded above with reasons). - ✅ CI enforces the import pattern via
eslint.config.js's scopedno-restricted-importsrule so future specs can't regress.
Per-surface verification (zero serious or critical violations on Home, Library, Search, etc.) is the V1-P2-3510..3519 work and is tracked separately. V1-P2-3500's tooling and enforcement obligations are met.