Eve library

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

Guide

Revision 1

On this page

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.