test: add live web platform smoke

[thymikee]

Summary

Add a gated live web platform smoke that runs on Node 24.13 in CI and exercises the public managed-backend path: web setup, web doctor, open, snapshot, get, is, wait, click, fill, screenshot, and close against a local fixture.

Closes #830

Touched files: 7. Scope stays in CI, maintainer testing docs, and integration-test utilities.

Validation

pnpm check:tooling
AGENT_DEVICE_WEB_E2E=1 pnpm test:smoke:web
pnpm check:quick

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstack.github.io/agent-device/pr-preview/pr-832/
Built to branch gh-pages at 2026-06-20 10:24 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.3 MB	1.3 MB	0 B
JS gzip	422.3 kB	422.3 kB	0 B
npm tarball	557.3 kB	557.3 kB	+21 B
npm unpacked	1.9 MB	1.9 MB	+95 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	26.5 ms	27.6 ms	+1.1 ms
CLI --help	44.6 ms	44.3 ms	-0.2 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

CI has two completed blockers right now:

1. .github/workflows/ci.yml:196-205 writes PNPM_HOME to $GITHUB_PATH, but that only affects later steps. The same step then immediately runs pnpm add --global, so pnpm still rejects the configured global bin dir:

[ERROR] The configured global bin directory "/home/runner/work/_temp/pnpm-global" is not in PATH

Export PATH="$PNPM_HOME:$PATH" in this step before pnpm config set global-bin-dir / pnpm add --global, or split the install into separate steps so $GITHUB_PATH has taken effect before the global install.

2. Fallow is also failing on the new test helper/test shape:

Unused exports: test/integration/test-helpers.ts:82 runCliJsonAsync
Large functions: test/integration/test-helpers.ts:133 createIntegrationTestContext 214 lines; test/integration/smoke-web-platform.test.ts:20 <arrow> 134 lines
High complexity: test/integration/smoke-web-platform.test.ts:20 <arrow>

runCliJsonAsync is exported only for the new context internals, so make it local or otherwise consume it through a public helper. Please also split the web smoke body into focused helpers (fixture setup, command assertions, cleanup) so the new lane passes the Fallow health guard before rerunning CI.

[thymikee]

After #833 merged into main, GitHub now reports this PR as not merge-ready (mergeStateStatus: UNSTABLE). The previous web smoke checks were green, but they ran before the current managed-backend changes on main; please update/rebase this branch onto latest main, resolve any web smoke/setup overlap, and rerun the required validation before merging.

[thymikee]

One remaining cleanup issue in test/integration/smoke-web-platform.test.ts: cleanupWebSmoke() currently awaits the close step before closing the fixture server or removing the socket dir. If agent-device close fails after the session has opened, runStep() throws and the function never reaches closeServer(context.server) or rmSync(context.socketDir, ...). That can leave the local HTTP server handle open and make the Node test hang until the CI job timeout, obscuring the real close failure. Please wrap the close attempt so server/socket cleanup always runs, then rethrow/report the close failure after local resources are released.

[thymikee]

Nice, well-instrumented smoke — the failure-artifact capture (step history + last snapshot) will make CI triage much easier, and extracting the shared cli-json.ts helpers out of test-helpers.ts is a clean refactor.

A couple of non-blocking observations:

1. Cleanup can leak the fixture server and socket dir on failure. In cleanupWebSmoke, the close web session step goes through runStep, which calls failWithContext → assert.fail when close returns non-zero. If that throws, closeServer(context.server) and the socket-dir rmSync never run, leaving a listening HTTP server and a /tmp/adw-* dir behind. Wrapping the close step in a try/finally (or try/catch) so server + socket teardown always runs would make cleanup robust even when the session fails to close.

2. socketDir is hardcoded to /tmp. That's clearly deliberate to keep the agent-browser socket path short (the macOS sun_path limit that #833 worked around), and the lane only runs on Linux/macOS CI, so it's fine in practice — just flagging that it isn't portable to Windows runners if that ever becomes a target. A short comment noting why /tmp is used instead of os.tmpdir() would save the next reader a double-take.

3. The new file matches the existing test:smoke glob (smoke-*.test.ts), so it'll be collected by the default pnpm test:smoke too — harmless since it's gated behind AGENT_DEVICE_WEB_E2E=1 and skips, just confirming that's intended.

None of these block; the core test logic and CI wiring look correct.

---

Generated by Claude Code

[thymikee]

Worker steering from latest review sweep (since 2026-06-19): please address the remaining cleanup issue before handing this back. In test/integration/smoke-web-platform.test.ts, cleanupWebSmoke() must always close the fixture server and remove socketDir even if agent-device close / runStep() throws; capture the close failure and rethrow or report it only after local resources are released. Current branch/check state is clean and green, so no rebase is requested unless main moves again.