Test strategy

Principles

The repeatable suite must prove browser authority without provider access. Unit, validator, development-browser, and production-browser runs are network-free and must pass with no API keys. Paid provider probes are separate evidence with an explicit launcher and authorization.

Test layers

Layer	Command or entrypoint	Purpose	External network
Type checking	pnpm run typecheck	Browser and Node contract consistency	No
Unit tests	pnpm run test	Domain, persistence, runtime, navigation, conversation, providers, characters, stage, world, and audio	No
Static validators	pnpm run validate:*	Simulation fixtures, shell, traffic, audio, graph, and font contracts	No
Combined validation	pnpm run validate	Type checking, unit tests, and all static validators	No
Documentation	pnpm run build:docs	Strict MkDocs navigation, links, warnings, and excluded source media	No
Development browser	pnpm run test:browser	Full deterministic office behavior plus mobile and accessibility integration	Disabled in Docker
Production browser	pnpm run test:browser:production	Minified normal composition with the development hook compiled out	Disabled in Docker
Full static build	pnpm run build	Validation, both Vite apps, docs, assembly, and dist/ route/resource validation	No provider network
Paid provider probes	Explicit paid launchers only	Authenticated DeepSeek or one MiniMax image	Explicit opt-in
Deployment smoke	scripts/deploy.sh	Candidate image, route boundaries, revision, cutover, and rollback	Local/public GET checks

pnpm run build runs, in order, validate, build:tour, build:graph, build:docs, scripts/assemble_site.mts, and scripts/validate_site.mts dist. The assembled-site validator expects a complete dist/; it is not a substitute for the standalone strict docs build.

Unit and contract coverage

The unit suite includes the following current release seams:

• exact event envelopes, source authority, expected revisions, contiguous sequence, pure reduction, invariant rejection, and atomic batch behavior;
• localStorage snapshots, expected-head conflicts, complete replay, corruption, sensitive-field rejection, compaction, and memory-store parity;
• seven-day clock bounds, focus acceleration, sleep, frame-stall clamping, whole-minute batching, scheduler checkpoints, reload equivalence, and Curator planning holds;
• actor schedules, needs, task utility, prerequisites, work progress, deadlines, collaboration, relationships, commitments, artifacts, build completion, and Day 7 campaign state;
• semantic-map validation, portal and door state, route planning, capacity reservations, replanning, release, and persisted movement reconstruction;
• foreground participant selection, knowledge audiences, public-only projection, deterministic conversation, proposal validation, stale results, event projection, Donna campaign exclusion, and advisory actor intents;
• silent Curator request projection, autonomous-founder targets, timeout/error fallback, stale authority, and exact DeepSeek schemas;
• DeepSeek request limits, cancellation, timeout, structured repair, error redaction, and malformed output;
• MiniMax fixed-prompt requests, provider errors, response caps, Base64, JPEG and PNG structure, APNG rejection, dimensions, trace IDs, and decode boundaries;
• stylized character resource sharing, poses, expression/activity projection, living-stage routes, collision registration, room placards, delivery, D&D, artifacts, and disposal;
• authoritative weather mapping and daily music-genome projection into the existing sky, lighting, precipitation, and score systems.

Browser modes

pnpm run test:browser copies only required source and configuration into a temporary .build/browser-test-* context. It mounts node_modules read-only and runs a digest-pinned Playwright 1.62.1 image as pwuser with a read-only root, private /tmp, dropped capabilities, no-new-privileges, a PID limit, and --network none. .git, .env*, existing builds, and unrelated repository files are excluded.

The development configuration serves Vite on port 4174, uses one Chromium worker, and excludes production.spec.ts. Its ?office-test=1 path is guarded by import.meta.env.DEV; tests use that deterministic reduced boot where useful and also load / to verify normal development composition.

The development browser suite verifies:

• five autonomous founder entities, six workstations, Jesse embodied only as #player, and Donna absent until introduced;
• Model Setup focus trapping, BYOK warning, opt-in raw-key persistence, configured placeholders after reload, and clearing;
• proximity-gated and keyboard-reachable conversations, deterministic event-log projection, inert typing, and no secret fields in stored campaign data;
• twice-confirmed Donna introduction and hire, candidate non-interactivity, authored entrance routing, and donna.transitioned persistence;
• task focus, 20x authoritative time, progress, movement interruption, and HUD state;
• build-terminal progress and the completed fixed 4 by 3 Relay Run playable;
• room-purpose placard projection from the same seeded completed-build state;
• event-log reload, a new run identity, BFCache freeze/resume without catch-up, one authoritative world-clock projection, and explicit memory-only continuation after a mid-run storage failure;
• narrow touch composition through the Pixel 5 project settings;
• real mouse and touch activation against the same world-raycast target in a touch-capable desktop context.

pnpm run test:browser:production uses the same isolation but selects only production.spec.ts. It builds the tour into container /tmp, previews it on port 4175, and loads /?office-test=1. Production must ignore that query hook and boot the normal minified office. Assertions cover the real player components and renderer, living stage, five autonomous characters, HUD and task button, absence of retired controls, minuteOfDay === absoluteMinute % 1440, and an accepted deterministic proximity conversation without page errors.

Accessibility and lifecycle cases

• Menus, Model Setup, task controls, nearby conversation, staffing, artifacts, and the playable have keyboard or ordinary HTML control paths.
• Modal presentation disables movement, contains focus, supports Escape and a visible Close control, and returns focus to a meaningful invoker.
• Typing movement keys in conversation does not move Jesse.
• Status changes use bounded text and restrained live regions.
• Reduced-motion tests retain final state and readable conversation output without depending on animation wall-clock timing.
• Mobile tests assert that the HUD, task drawer, and conversation panel remain inside a narrow touch viewport.
• BFCache tests prove persisted pagehide freezes the campaign and pageshow resumes without converting hidden wall time into simulated minutes.

Paid-test policy

Paid checks are never invoked by validation, build, ordinary browser tests, or deployment. The protected commands are:

pnpm run test:browser:deepseek
pnpm run test:browser:paid
pnpm run smoke:minimax -- --paid --max-requests=1

Do not run any of them without explicit current authorization. The DeepSeek foreground and Curator adapters allow one structured repair, so one logical action can make up to two calls. MiniMax is fixed to one 512 by 512 image per request. The original MiniMax authorization allowed three requests and is treated as exhausted after one Node success, one browser timeout, and one browser success.

Paid launchers require the selected key from the environment or local .env, enable networking only for their disposable test, and forward only that key to the Playwright worker. Commands print bounded metadata and file paths, never the key or full Base64 response. Ambient PAID_* variables cannot opt an ordinary test into provider access.

Repeatable release gate

pnpm run validate
pnpm run test:browser
pnpm run test:browser:production
pnpm run build
docker build --build-arg VCS_REF="$(git rev-parse HEAD)" -t suite666:smoke .

pnpm run build intentionally reruns validation before producing the assembled site. Deployment additionally runs both browser modes, candidate-container and public route matrices, and the exact /revision check. Paid probes remain absent from every repeatable gate.