Test Harness

Use this reference when putio-frontend-repos work touches proof loops for put.io frontend-owned web, browser extension, TV, native, emulator, simulator, or device surfaces.

A useful harness wraps platform tools, exposes a typed command surface, prepares auth/session state, drives real product flows, asserts meaningful state, and leaves proof artifacts.

Workflow

1. Read harness pattern before shaping architecture, platform notes before picking tools, and examples when you need concrete precedent.
2. Inspect the target surface, wrapped platform tools, existing repo commands, local docs, and auth/session entrypoints before designing anything new.
3. Design the harness layers explicitly: adapter, CLI/API, auth/session, flow driver, assertions, proof artifacts, repo integration, observability, isolation, and boundaries.
4. Keep the generic harness core focused on the test surface. Put product journeys, fixture names, content IDs, credentials, and expectations in the owning app repo or scenario files.
5. For auth/session, follow the testing-account, global putio profile, and one-shot secret-materialization rules in harness pattern.
6. Make human browser login, repeated secret approvals, and personal accounts explicit fallback paths, not the default harness design.
7. Prefer deterministic commands and typed outputs over prose-only manual steps. Use narrow commands that are bootable, smokeable, interactable, observable, and isolated enough for agents to debug without repeated human help.
8. Before implementation, check every harness layer from step 3 is covered. If a layer is missing, revise the design before writing code.
9. After implementation, run the smoke or live-test entrypoint, inspect proof artifacts and logs, fix the root cause of failures, and rerun. If the platform cannot expose state directly, require stronger screenshots, logs, recordings, or review artifacts.

Mini-example command surface:

harness package --profile <profile-name>
harness install --device <device-alias>
harness launch --app <app-id>
harness open-flow --name playback --fixture <fixture-name>
harness press --key play-pause
harness auth-status --profile <profile-name>
harness auth-prepare --profile <profile-name>
harness auth-render-vars --profile <profile-name> --env-file <ignored-env-file>
harness auth-approve-device --profile <profile-name> --code <device-code>
harness seed-account --profile <profile-name> --scenario <scenario-name>
harness assert-screen --name player --artifact artifacts/live/player.png

The exact command names should follow the target repo, but the shape should stay narrow, typed, and proof-producing.

Minimal TypeScript shape:

type HarnessArtifact = {
  kind: "screenshot" | "log" | "state" | "review-html";
  path: string;
};

type HarnessResult = {
  status: "ok" | "failed";
  device: string;
  artifacts: HarnessArtifact[];
  message?: string;
};

interface PlatformAdapter {
  package(profile: string): Promise<HarnessResult>;
  install(device: string): Promise<HarnessResult>;
  launch(appId: string): Promise<HarnessResult>;
  press(key: string): Promise<HarnessResult>;
  screenshot(path: string): Promise<HarnessResult>;
}

Output Shape

For a harness design or implementation plan, report the adapter, command surface, auth/session path, flow driver, assertions, proof artifacts, repo integration, observability, isolation, and remaining boundaries.

Guardrails

• Keep device IPs, passwords, certs, signing keys, tokens, content IDs, fixture internals, and personal local facts out of git.
• Checked-in examples use placeholders.
• Keep auth/session automation on named testing profiles and ignored local config paths. Do not spin on approval prompts or persist raw rendered secrets in checked-in files.
• Infisical-backed harness secrets must be limited dev/test accounts and fixtures, never admin accounts, production-wide credentials, signing keys, recovery keys, or CI/CD deploy/publish secrets.
• Repo .env.local or .env examples may name a profile or config path, but must not contain raw put.io tokens.
• Keep product business logic out of generic platform commands.
• Wait for meaningful runtime conditions instead of arbitrary sleeps.