ai_synth/docs/superpowers/specs/2026-03-22-test-coverage-documentation-design.md

Design: Test Coverage & Documentation Improvements

Date: 2026-03-22 Source: docs/tech_lead_assessment_Coverage_Documentation.md Scope: 5 improvements — frontend page tests, frontend JSDoc, backend test gaps, E2E tests

---

Context

The tech lead assessment graded the backend A (332 unit + 145 integration tests, good documentation) and the frontend C (103 utility/API tests only, weak documentation). Every page and component has zero test coverage. This design addresses all 5 recommendations from the assessment.

---

1. Frontend Component/Page Tests

Goal

Add interaction-level tests for the 5 most critical pages using @solidjs/testing-library + Vitest + MSW.

Test Infrastructure

• MSW (Mock Service Worker) to intercept fetch calls in tests
• Shared test-utils.ts with a renderWithProviders() helper that wraps components in AuthContext, I18nProvider, ToastProvider, and Router
• Mocked Turnstile — stub window.turnstile in test setup
• Mocked EventSource — stub for SSE tests in GenerateSynthesis

Pages and Tests (~39 tests)

Settings.tsx (~10 tests)

• Renders form with all fields populated from API response
• Save button calls PUT /settings with form data
• Provider dropdown populated from config API
• Selecting provider updates model dropdown options
• Dual model dropdowns render (research + writing)
• Rate limit section renders with null values (empty inputs)
• Rate limit section shows effective rate when values set
• Reset link clears rate limit fields to null
• Export downloads JSON file
• Import populates form from uploaded JSON

Home.tsx (~7 tests)

• Renders synthesis list from API response
• Empty state shows when no syntheses
• "Nouvelle Synthese" button links to /generate
• Delete first click shows "Confirmer" state
• Delete second click removes synthesis from list
• Delete auto-cancels after 3 seconds
• In-progress banner shows when a synthesis has status "in_progress"

Sources.tsx (~8 tests)

• Renders source list from API response
• Empty state shows when no sources
• Add form validates empty title/URL
• Add form submits and new source appears in list
• Delete with confirmation removes source
• Bulk import textarea parses and imports
• CSV export triggers download
• CSV import triggers file picker

Login.tsx + Register.tsx (~8 tests)

• Login renders email input and submit button
• Login submit calls POST /auth/login
• Login shows "check inbox" message on success
• Login shows error on API failure
• Resend button disabled during cooldown
• Register renders email + display name + submit
• Register submit calls POST /auth/register
• Register shows confirmation on success

GenerateSynthesis.tsx (~6 tests)

• Renders launch button with settings info
• Launch button calls POST /syntheses/generate
• Progress bar updates from SSE events
• Step checklist shows done/in-progress/pending states
• Completion redirects to synthesis detail
• Error state shows retry button

Dependencies to Add

• msw (dev dependency) for API mocking
• No other new dependencies needed (@solidjs/testing-library already installed)

---

2. Frontend JSDoc Documentation

Goal

Add English JSDoc comments to all exported components, functions, and complex logic blocks. No code changes.

Scope

API Layer

• api/client.ts — class purpose, CSRF strategy (X-Requested-With), credential handling (same-origin), 401 redirect behavior
• api/auth.ts, api/settings.ts, api/sources.ts, api/syntheses.ts, api/admin.ts, api/config.ts, api/apiKeys.ts — brief JSDoc on each exported function

Pages (complex logic)

• pages/Settings.tsx — export/import logic, provider auto-detection, rate limit null handling, dual model state management
• pages/GenerateSynthesis.tsx — SSE state machine (idle -> connecting -> progress -> complete/error), step progression, reconnection, completion redirect timer
• pages/Home.tsx — delete confirmation timer pattern (first click -> confirm state -> 3s auto-cancel)
• pages/Sources.tsx — bulk import parsing, CSV import/export flow, URL normalization
• pages/SynthesisDetail.tsx — email send flow, file download mechanism (Blob + anchor)
• pages/Login.tsx, pages/Register.tsx — Turnstile lifecycle, resend cooldown timer
• pages/AuthVerify.tsx — token extraction from URL, verification flow

Components

• components/ApiKeyManager.tsx — key CRUD flow, show/hide toggle, test button
• components/Turnstile.tsx — widget lifecycle, polling initialization, cleanup
• components/Navbar.tsx — active route detection, admin link visibility
• components/MobileMenu.tsx — escape key handler, backdrop click
• components/Layout.tsx, components/AdminLayout.tsx — layout structure, sidebar nav
• components/ErrorBoundary.tsx — error catching, retry mechanism
• components/ui/Button.tsx — props interface, variant behavior (primary/secondary/danger)
• components/ui/Toast.tsx — toast provider pattern, auto-dismiss timer
• components/ui/LoadingSpinner.tsx — size/fullPage props

Utilities

• utils/sse.ts — reconnection backoff logic (exponential, max 3 retries), event type parsing, cleanup
• utils/dates.ts — date-fns locale configuration
• utils/providers.ts — provider capability detection

Context

• contexts/AuthContext.tsx — session check on mount, 401 handling, isAdmin derived signal

Style

• Brief /** ... */ on exports
• Inline // comments only for non-obvious logic (state machines, timers, edge cases)
• No boilerplate comments on trivial code (simple getters, obvious props)

---

3. Backend Test Gaps

3a. Schema Builder Tests (services/llm/schema.rs) — 6 tests

• test_schema_single_category — 1 category produces category_0 with correct item schema
• test_schema_five_categories — 5 categories produce category_0 through category_4
• test_schema_twenty_categories — max 20 categories all present
• test_schema_special_characters — category names with accents, quotes, ampersands don't break JSON
• test_schema_long_category_name — 200-char category name accepted
• test_schema_item_structure — each category value is array of {title: string, url: string, summary: string}

3b. Auth Middleware Unit Tests (middleware/auth.rs) — 5 tests

• test_valid_session_cookie_extracted — properly formatted cookie returns token
• test_malformed_cookie_no_equals — cookie without = returns None
• test_missing_cookie_header — no Cookie header returns Unauthorized
• test_multiple_cookies_correct_one_picked — session cookie found among other cookies
• test_cookie_with_whitespace — leading/trailing whitespace trimmed

3c. Token Utility Tests (util/token.rs) — 4 tests

• test_generated_token_length — base64url-encoded token has expected length
• test_tokens_are_unique — two consecutive generated tokens differ
• test_hash_is_deterministic — same input produces same hash
• test_hash_differs_from_raw — hash output is not the raw token

Total: 15 new backend unit tests, bringing count from 332 to ~347.

---

4. E2E Tests with Playwright

Infrastructure

e2e/docker-compose.test.yml:

• Extends main docker-compose.yml
• Uses a test-specific Postgres database (fresh per run)
• App service with TEST_DATABASE_URL and test Turnstile/Resend keys
• Exposes app on port 8080

e2e/seed.ts:

• Node.js script connecting directly to test Postgres
• Creates admin user (email_verified, role=admin) with a known session token
• Creates regular test user with a known session token
• Both sessions have 30-day expiry

e2e/helpers/auth.ts:

• loginAsAdmin() — sets session cookie for admin
• loginAsUser() — sets session cookie for regular user
• registerAndVerify(email) — inserts magic link token in DB, navigates to verify URL
• Direct DB access via pg npm package for token extraction

e2e/playwright.config.ts:

• Base URL: http://localhost:8080
• Timeout: 30s per test
• Retries: 1
• Screenshots on failure

Test Flows (5 specs)

registration.spec.ts

• Navigate to /register
• Fill email, submit (Turnstile bypassed via test key)
• Extract magic link token from DB
• Navigate to /auth/verify?token=...
• Assert: redirected to Home, user email shown in navbar

admin-providers.spec.ts

• Login as admin (cookie injection)
• Navigate to /admin/providers
• Enable Gemini provider, add a model
• Save
• Assert: provider appears in GET /config/providers response

settings.spec.ts

• Login as user
• Navigate to /settings
• Change theme, select provider + models, save
• Reload page
• Assert: all saved values repopulated

sources.spec.ts

• Login as user
• Navigate to /sources
• Add a source (title + URL)
• Bulk import 3 sources
• Assert: 4 sources in list
• Delete one
• Assert: 3 sources remain
• Export CSV
• Assert: downloaded file contains 3 rows

settings-export.spec.ts

• Login as user
• Configure settings (theme, categories, models)
• Export JSON
• Change settings to different values, save
• Import the exported JSON
• Save
• Reload
• Assert: original values restored

File Structure

e2e/
├── playwright.config.ts
├── docker-compose.test.yml
├── package.json              — playwright, pg dependencies
├── seed.ts
├── helpers/
│   └── auth.ts
└── tests/
    ├── registration.spec.ts
    ├── admin-providers.spec.ts
    ├── settings.spec.ts
    ├── sources.spec.ts
    └── settings-export.spec.ts

---

Summary

Section	New Tests	New Docs	Effort
Frontend page tests	~39	—	Large
Frontend JSDoc	—	~30 files	Medium
Backend test gaps	~15	—	Small
E2E tests	~5 flows	—	Large
Total	~59 tests + 5 E2E flows	~30 files documented

Implementation Order

1. Backend test gaps (small, independent, quick win)
2. Frontend JSDoc (no code changes, can't break anything)
3. Frontend page tests (requires MSW setup first, then tests)
4. E2E tests (requires Docker test infrastructure, depends on everything else working)