Interactive Testing

Interactive Testing — Poracode

Test the real Electron renderer, preload bridge, main process, and supervisor integration. Treat unit tests as complementary; do not substitute them for this workflow when the skill triggers.

Required workflow

1. Inspect git status --short and the relevant diff.

2. Choose the validation shape below before launching anything.

3. For an ordinary quick or full smoke, run its one-command runner directly; it creates the isolated fixture, boots the app, derives the scope plan, runs the checks, and tears the app down.

4. For a manual live check, generate the plan, then start or reuse one managed debug session:

   node .agents/skills/interactive-testing/scripts/poracode-integration-smoke.mjs plan --scope changed
   node .agents/skills/interactive-testing/scripts/run-poracode-smoke.mjs --launch-only --mode mock

5. Audit the functional inventory only when changing scripts/smoke-scenarios.mjs, adding a production surface, or investigating coverage selection:

   node .agents/skills/interactive-testing/scripts/poracode-integration-smoke.mjs audit

6. Use fixture projects, deterministic store state, and mocked provider/auth/runtime data for local regression coverage. The runner executes these gates automatically and reports them as mocked.

7. Use --mode real only when real credentials, devices, or external services are intentionally available; complete and acknowledge those gates with --ack-manual.

8. Reset driven state, stop only the process launched for this run, inspect unexpected git changes, and report evidence.

Never claim “all functionality passed.” Report automated, manual, skipped, and not-applicable coverage separately.

Choose the validation shape first

Use the smallest path that proves the requested behavior. Do not run more than one app-launch command for a single validation run.

Use the quick smoke by itself when the user asks to “smoke test,” “check the app,” or “make sure this did not regress.” Use the real workflow when the user asks whether a provider, ACP/tool call, login, device, PTY, or other external integration works live. Run the full smoke only for release-scale, broad cross-cutting, IPC/app-shell, or cross-provider changes.

Boot an isolated app

Choose exactly one launch path per test run. Never use raw pnpm run dev or pnpm run dev:test for CDP work: those commands do not allocate a managed session and make wrong ports, shared state, and duplicate launches possible. The smoke runner owns and tears down its app. The managed launcher keeps one app alive for repeated manual actions, and its owner process performs every stop.

The one-command runner below allocates its own free ports, so each invocation spawns a fully isolated dev app. Runs from multiple worktrees can execute side by side without colliding on the Vite or CDP port.

node .agents/skills/interactive-testing/scripts/run-poracode-smoke.mjs --scope changed --mode mock

For slow cold starts, pass --startupTimeoutSeconds 450 to the runner. This overrides the default 180-second app-readiness deadline; scenario timeouts stay unchanged.

This allocates distinct free dev-server and CDP ports (override with --vitePort/--port; explicit values are verified free), creates and commits a disposable fixture project, seeds an isolated database, starts Electron with an isolated profile and compiled runtime, dismisses and verifies the first-launch welcome screen, runs the integration suite, writes screenshots/report artifacts under ~/.poracode-smoke, and tears down the process automatically. Managed launches never reclaim an occupied port or rebuild another session's runtime. No provider credentials, PTY input, git mutations, MCP server, mobile device, or native update flow is required for the default mock run.

HOME and provider detection — no drift between test and app. Poracode's own state is always isolated via PORACODE_BASE_DIR, independent of HOME. Provider detection, however, resolves each CLI through the login-shell command -v (e.g. kimi → ~/.kimi-code/bin/kimi) and reads credentials under the home dir — so it only matches the real app when HOME is the real home. Therefore:

• Mock mode sandboxes HOME/APPDATA and uses a mock keychain (deterministic isolation; providers are mocked). Real providers legitimately show "Not found" here — that is expected, not a bug, and mock gates never depend on real credentials.
• Real mode (--mode real) keeps the real HOME, so authenticated providers (Kimi, Qwen, …) can detect as in the shipped app. Always verify a provider-dependent surface in real mode; never diagnose a real detection issue from a mock-mode "Not found".

Real HOME is necessary but not always sufficient: detection probes command -v <binary> in a login+interactive shell with cwd: homedir(), so a CLI whose bin dir is on PATH only via a project-scoped mechanism (direnv .envrc, asdf local, mise, a per-repo .env) is invisible to the detector even though it works inside the project — direnv unloads at the home cwd. Symptom: the app log prints direnv: unloading and the provider shows "Not found". Fix in the environment, not the app: put the binary on a globally-resolvable PATH (e.g. symlink into ~/.local/bin, as qwen/grok are). This is why ~/.kimi-code/bin/kimi (direnv-only) can miss while ~/.local/bin-installed providers detect fine.

For a persistent interactive app, use the managed launcher:

node .agents/skills/interactive-testing/scripts/run-poracode-smoke.mjs --launch-only --mode mock
# Use the real HOME and provider credentials only when the task needs them:
node .agents/skills/interactive-testing/scripts/run-poracode-smoke.mjs --launch-only --mode real

When an agent must launch an intentionally independent session and then keep working in the same turn, use the detached CDP launch command instead of inventing a Start-Process, shell-redirection, or helper-script wrapper:

node .agents/skills/interactive-testing/scripts/poracode-cdp.mjs launch --new --mode mock --root "$HOME/.poracode-smoke/<unique-agent-root>"

It returns only after READY and prints the exact sessionFile, ports, URL, owner PIDs, and launch time. --new plus a fresh unique root is mandatory so parallel agents cannot reuse or stop each other's apps. Its default 180-second deadline accommodates several concurrent cold Vite transforms; once READY, individual CDP actions should still finish in milliseconds, not inherit that cold-start budget.

The command allocates ports, creates the fixture, isolates the compiled Electron bundle and runtime resources, skips the welcome gate, and waits until the main renderer has a mounted root plus preload and DEV bridges. It prints READY only after those checks pass. Keep that exact terminal alive. When testing is complete, request verified teardown from any shell with:

node .agents/skills/interactive-testing/scripts/poracode-cdp.mjs stop

The stop command returns success only after the owner has closed both ports, removed its isolated build, and marked session.json stopped. Ctrl-C in the owning terminal is a fallback and uses the same teardown path, but some Windows PTY hosts report the outer shell interruption as exit 1 even after clean teardown. A cold renderer transform can take about a minute on a busy Windows checkout; state: "starting" still owns the launch, so wait for READY or a concrete failure instead of starting another app.

The launcher reuses an existing healthy debug session for this checkout instead of launching a duplicate. Only use --new when concurrent same-checkout apps are the behavior under test. If more than one session exists, every helper refuses to guess; pass the exact session printed by its launcher:

node .agents/skills/interactive-testing/scripts/poracode-cdp.mjs info --session "<session.json path printed by launcher>"

The authoritative <run-id>/session.json records the unique token, lifecycle, repo/worktree, app URL, distinct ports, base directory, isolated build, and owner PIDs. ports.json remains report metadata, not an attachment instruction. Never invent a port or copy one from another run. The helpers accept a complete explicit port + URL pair only for deliberate unmanaged-app diagnosis; they reject either value alone and have no 9222/3100 fallback.