DUNIN7-M4 — INFRASTRUCTURE CHANGE REQUEST

CR-2026-034 — Phase 20: Frontend Test Framework (v0.1)

Version. 0.1 Date. 2026-04-27 Author. Marvin Percival (DUNIN7), prepared via Claude. Target. /Users/dunin7/loomworks-ui (frontend) on DUNIN7-M4 (MacMini). Substrate unchanged. Priority. Standard. Confidential. Internal. Supersedes. Nothing for Phase 20 specifically. Companion to. Phase 20 scoping note v0.1. Resolves Residue 16 (carried since Phase 14). Status. First draft. Infrastructure phase — ships the test framework, not a feature. Consumes five settled scoping decisions (S1–S5).

1. Executive summary
2. Prerequisites
3. Framework installation and configuration
4. Test helpers and mocking patterns
5. Component tests (Vitest + React Testing Library)
6. E2E tests (Playwright)
7. Package.json scripts
8. Order of operations (steps with checkpoints)
9. Acceptance gate
10. Post-CR state
11. What this CR does not specify
12. Kickoff prompt for the Claude Code session

1. Executive summary

Phase 20 establishes the frontend test framework. Two layers: Vitest + React Testing Library for component-level tests (rendering, props, conditional display, error states) and Playwright for end-to-end tests (auth flow, navigation, contribution, derive). The phase ships installation, configuration, test helpers, and a first batch of tests covering the highest-risk surfaces.

This resolves Residue 16, carried since Phase 14. After Phase 20, the frontend verification step in future CRs becomes lint + tsc + build + test clean.

No substrate changes. Frontend-only.

2. Prerequisites

2.1 Baseline

Frontend repo: at HEAD after Phase 19 amendment commits. Lint + tsc + build clean. Eleven surfaces.
Substrate: running at localhost:8000 (required for E2E tests). 1124 tests, 2 skips.
Loomworks engagement: 12 committed assertions, at least one Manifestation derived with organized groups. This provides real data for E2E tests.

2.2 Pre-flight checks

Frontend repo builds clean.
Substrate is running and the Loomworks engagement is accessible.
No existing test configuration files (vitest.config.ts, playwright.config.ts). If present, reconcile.
Node version supports the chosen libraries.

2.3 CR archival

Archive this CR to docs/phase-crs/phase-20-cr-frontend-test-framework-v0_1.md in the substrate repo at Step 0 before Step 1 begins.

3. Framework installation and configuration

3.1 Component tests — Vitest + React Testing Library

Install:

vitest (test runner)
@testing-library/react (component rendering and queries)
@testing-library/jest-dom (DOM matchers)
@vitejs/plugin-react (JSX transform for Vitest)
jsdom (DOM environment for Vitest)

Configuration: vitest.config.ts at repo root. Must resolve Next.js path aliases (@/), handle CSS modules (stub or identity transform), and configure jsdom as the test environment. CC determines the exact configuration for compatibility with Next.js 16 and Turbopack.

3.2 E2E tests — Playwright

Install:

@playwright/test
Playwright browsers (npx playwright install chromium — Chromium only for localhost testing)

Configuration: playwright.config.ts at repo root. Base URL: http://localhost:3000. No automatic dev server start — the dev server must be running (same as manual testing). Timeout: 30s per test (LLM-dependent flows like Manifestation derivation need headroom). Single browser (Chromium). Screenshots on failure.

3.3 Directory structure


tests/
  components/          # Vitest + RTL component tests
    AssertionCard.test.tsx
    HeldAssertionCard.test.tsx
    EngagementPickerModal.test.tsx
    RoomSwitcher.test.tsx
    ContributionSurface.test.tsx
    ManifestationRoom.test.tsx
  e2e/                 # Playwright E2E tests
    auth.spec.ts
    contribution.spec.ts
    derive.spec.ts
    navigation.spec.ts
  helpers/             # Shared test utilities
    mock-data.ts       # Deterministic test fixtures
    mock-providers.tsx  # Context wrappers for component tests
    test-setup.ts      # Global setup for Vitest

CC may adjust the structure based on Next.js 16 conventions. The structure is a starting point, not a constraint.

4. Test helpers and mocking patterns

4.1 Component test mocking

Component tests do not call the substrate. A mock approach wraps components with stubbed fetch or context providers. CC determines the best pattern for the codebase — options include:

Mock fetch globally in test setup (intercept API calls, return deterministic data).
Mock the lib/api.ts module (the API client layer) via Vitest's module mocking.
Provide mock data via props where components accept data as props rather than fetching internally.

The chosen pattern should be consistent across all component tests.

4.2 Mock data fixtures

tests/helpers/mock-data.ts exports deterministic test data: mock assertions (with display numbers, provenance, metadata), mock engagements, mock memberships, mock Manifestation (with and without organized groups), mock memory-status response, mock downstream-impact response. All UUIDs and timestamps are deterministic.

4.3 E2E test data

E2E tests run against the live substrate with real data. The Loomworks engagement (12 assertions, derived Manifestation) serves as the primary test engagement. E2E tests that modify state (contribute an assertion, derive a Manifestation) should clean up after themselves where possible, or use assertions that are discarded (not committed).

4.4 WebAuthn in E2E

Playwright supports virtual authenticators. The sign-in E2E test registers a virtual authenticator before the sign-in flow, eliminating the need for a physical passkey. CC implements this per Playwright's WebAuthn documentation. TOTP verification can be computed from the person's TOTP secret (available in the test setup) using a TOTP library (e.g., otpauth).

5. Component tests (Vitest + React Testing Library)

5.1 AssertionCard

Renders content text.
Shows display number (#N) for committed assertions.
Shows no display number for held assertions.
Shows provenance line (contributor name, timestamp, source mode).
Shows "Retracted" state with rationale for retracted assertions.
Shows redirect provenance ("Redirected from [name]") when metadata present.

5.2 HeldAssertionCard

Shows Commit, Redirect, and Discard buttons.
Redirect button hidden when no eligible target engagements.
Redirect button visible when eligible targets exist.
Commit calls the commit endpoint (mocked).
Discard calls the retract endpoint with "Discarded before commit" rationale (mocked).

5.3 EngagementPickerModal

Renders engagement list filtered to contributor/operator memberships.
Excludes current engagement.
Single-select — clicking one engagement highlights it, clicking another switches.
Confirm button disabled until selection made.
Cancel closes modal.
Empty state: no eligible engagements.

5.4 RoomSwitcher

Renders four room entries.
Memory entry is always clickable.
Manifestation entry clickable when version is non-null, count-only when null.
Active room has correct environment tint.
Counts display correctly.

5.5 ContributionSurface

Mode selector shows available modes.
Text mode: textarea renders, "Add to Memory" button present.
Text submission creates held assertion (mocked API call).
Mode switching changes the visible form.

5.6 ManifestationRoom

Empty state renders derive prompt with Memory summary counts.
Organized view renders rationale in italic.
Organized view renders groups with labels and assertions.
History toggle shows/hides superseded Manifestations.
Derive button disabled when no API key (mocked state).
Fallback: Manifestation without organized_groups shows summary card.

6. E2E tests (Playwright)

6.1 Sign-in flow

Navigate to localhost:3000.
See landing page with "Sign in with passkey" button.
Use virtual authenticator to complete passkey ceremony.
Complete TOTP verification (computed from known secret).
Arrive at dashboard.
See engagement cards.

6.2 Contribution flow

From dashboard, click Loomworks engagement.
Navigate to Memory room (via lobby or room switcher).
See contribution surface.
Type text in textarea.
Click "Add to Memory."
See held assertion appear.
Click "Commit" on the held assertion.
See assertion appear in committed Memory with display number.
Clean up: retract the test assertion (or leave it — it becomes part of the engagement's Memory).

6.3 Derive flow

Navigate to Manifestation room for the Loomworks engagement.
Click "Re-derive Manifestation."
See preview modal with rationale and proposed groups.
Click "Confirm derivation."
See organized view with groups and assertions.
Verify rationale is displayed.

6.4 Navigation

Room switcher: click Memory → Memory room. Click Manifestation → Manifestation room.
Lobby: badges link to rooms.
Back-to-lobby link works.
Dashboard: engagement cards link to lobbies.
Sign out: returns to landing page.

7. Package.json scripts


{
  "test": "vitest run",
  "test:watch": "vitest",
  "test:e2e": "playwright test",
  "test:e2e:headed": "playwright test --headed",
  "test:all": "vitest run && playwright test"
}

CC adjusts as needed. The key constraint: npm run test runs component tests only (fast, no substrate needed). npm run test:e2e runs E2E tests (requires running substrate and dev server). npm run test:all runs both.

8. Order of operations (steps with checkpoints)

Auto-mode posture: Steps 1–3 auto, Checkpoint A. Steps 4–6 auto, Checkpoint B (final).

Step 0 — Pre-flight and CR archival.

Archive this CR (to substrate repo). Confirm prerequisites (Section 2.2).

Commit (substrate repo): Phase 20 step 0: CR archival.

Step 1 — Framework installation and configuration.

Install Vitest + RTL + Playwright. Create configuration files. Create directory structure. Create test helpers (mock data, mock providers). Verify npm run test runs (zero tests, but framework loads).

Commit (frontend repo): Phase 20 step 1: test framework installation and configuration.

Step 2 — Component tests: assertion cards and engagement picker.

Write tests for AssertionCard, HeldAssertionCard, EngagementPickerModal (Sections 5.1–5.3).

Verification: npm run test passes.

Commit (frontend repo): Phase 20 step 2: component tests — assertion cards and engagement picker.

Step 3 — Component tests: room switcher, contribution surface, manifestation room.

Write tests for RoomSwitcher, ContributionSurface, ManifestationRoom (Sections 5.4–5.6).

Verification: npm run test passes. All component tests green.

Commit (frontend repo): Phase 20 step 3: component tests — room switcher, contribution, manifestation.

Checkpoint A — Component test framework complete. All component tests pass. Operator confirms before E2E work begins.

Step 4 — E2E tests: auth and navigation.

Write auth flow and navigation E2E tests (Sections 6.1, 6.4). This step proves the Playwright setup works end-to-end with virtual authenticator and TOTP computation.

Verification: npm run test:e2e passes (with substrate and dev server running).

Commit (frontend repo): Phase 20 step 4: E2E tests — auth and navigation.

Step 5 — E2E tests: contribution and derive flows.

Write contribution flow and derive flow E2E tests (Sections 6.2, 6.3).

Verification: npm run test:e2e passes. All E2E tests green.

Commit (frontend repo): Phase 20 step 5: E2E tests — contribution and derive flows.

Step 6 — Implementation notes and tagging.

Create docs/phase-impl-notes/phase-20-implementation-notes-v0_1.md in the substrate repo.

Commit (substrate repo): Phase 20 step 6: implementation notes.

Checkpoint B — Final. Frontend: lint + tsc + build + test clean. E2E tests pass. Tag both repos as phase-20-frontend-test-framework.

9. Acceptance gate

Phase 20 is accepted when:

Substrate: all tests still pass (1124, 2 skips). No substrate changes.
Frontend: lint + tsc + build clean.
npm run test passes — all component tests green.
npm run test:e2e passes — all E2E tests green (with substrate running).
Component tests cover: assertion cards, engagement picker, room switcher, contribution surface, manifestation room.
E2E tests cover: sign-in, contribution, derive, navigation.
Mock data fixtures and providers are reusable for future tests.
Residue 16 is resolved.

On acceptance: tag both repos as phase-20-frontend-test-framework. Write implementation notes.

10. Post-CR state

Substrate: 1124 tests, 2 skips (unchanged).
Frontend: lint + tsc + build + test clean. ~15–20 component tests. ~4 E2E test files. Eleven surfaces (unchanged).
Test commands: npm run test (component), npm run test:e2e (E2E), npm run test:all (both).
Future CR verification step: lint + tsc + build + test clean replaces lint + tsc + build clean.

Residue resolution

Residue 16 — Frontend test framework absent. Resolved. Framework installed, first batch of tests shipping, pattern established for future phases.

11. What this CR does not specify

Comprehensive coverage of all eleven surfaces. Phase 20 covers the highest-risk surfaces. Remaining surfaces gain coverage as future phases add features.
Visual regression / screenshot testing. Playwright supports it; deferred.
CI pipeline. Tests run locally on M4. CI is a future infrastructure item.
Performance testing. Not in scope.
Coverage reporting. Vitest supports it; can be enabled but no coverage threshold is set in Phase 20.

12. Kickoff prompt for the Claude Code session


> Read the Change Request document at the path I supply below. This is
> CR-2026-034 v0.1, the Phase 20 Change Request (first version; no
> prior Phase 20 CR exists). You are the executing agent named in the
> CR.
>
> CR path: ~/Downloads/phase-20-cr-frontend-test-framework-v0_1.md
>
> This is an infrastructure phase — test framework, not a feature.
> Resolves Residue 16 (zero frontend tests since Phase 14).
>
> Code baseline: frontend at HEAD after Phase 19 amendment commits.
> Substrate: 1124 tests, 2 skips, running at localhost:8000.
>
> Run pre-flight (Step 0) per Section 2.2.
>
> Per Section 2.3: archive this CR to
> docs/phase-crs/phase-20-cr-frontend-test-framework-v0_1.md in
> the substrate repo at Step 0.
>
> Per Section 8, six steps with two checkpoints. Auto-mode posture:
> Steps 1–3 accept auto-mode-proceed; Checkpoint A halts. Steps 4–6
> auto; Checkpoint B (final) halts for tagging.
>
> Component tests mock the substrate (no network calls). E2E tests
> require the substrate running at localhost:8000 and the dev server
> at localhost:3000. WebAuthn uses Playwright's virtual authenticator.
>
> Pre-flight surprises stop at Step 0 and drive a CR v0.2 revision.
>
> Implementation notes at Step 6:
> docs/phase-impl-notes/phase-20-implementation-notes-v0_1.md

DUNIN7 — Done In Seven LLC — Miami, Florida Phase 20: Frontend Test Framework — CR v0.1 — 2026-04-27