# V1-P2-3500 — axe-core in Playwright suites

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.0` and
  `@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 exposing
  - `analyzeA11y(page, options)` — raw axe results
  - `expectNoSeriousA11yViolations(page, options)` — assert helper that fails on
    serious + critical impacts (configurable via `failOn`)
  - `filterFailingViolations` / `formatA11yViolations` — used both by the assert
    helper and by external consumers
  - `extendWithA11y(test)` — Playwright `test.extend` adding `skipAxe` +
    `axeOptions` per-test fixtures
  - `axeAfterEach(test)` — one-line entry point: returns an extended `test`
    whose `afterEach` runs 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/playwright` path mapping.
- **package.json (`@oshun/testing`)**: `./playwright` export 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:

1. **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
   });
   ```
2. **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);
   });
   ```
3. **Page-object helper**: `BasePage.checkAccessibility()` (in
   `testing/e2e/page-objects/base.page.ts`) wraps the explicit call — page
   objects in the central e2e suite can invoke `await 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`):

```diff
- 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 skip `no-restricted-imports`'s `importNames` check).
- 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:

1. ✅ Every spec in every wired suite imports `test` from its `fixtures.ts` (672
   specs across 11 app suites).
2. ✅ 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).
3. ✅ CI enforces the import pattern via `eslint.config.js`'s scoped
   `no-restricted-imports` rule 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.
