Local Browser Connector

The Local Browser Connector lets Testver drive a browser on your own machine instead of one running on the Testver server. The UI experience is identical — you still see the live screencast, click through the recorder, watch the AI Assistant operate the browser — but every command actually executes against a Playwright instance running locally on your laptop.

Why use it

The default flow runs browsers on the Testver server. That’s perfect for cloud / shared deployments. It falls short when:

• The site you’re testing requires SSO / VPN / corporate network access. The server doesn’t have that; your laptop does.
• You need a specific browser profile (signed-in to a real account, with extensions installed, with saved cookies).
• Compliance or data-residency rules keep test traffic off shared infrastructure.
• Testver is hosted but your test target isn’t reachable from it.

When a connector is registered for your user, AI Record, AI Assistant Web mode browser tools, and direct browser tool calls all transparently route to your local browser. No code changes, no settings toggles per-test.

How it works

A small CLI agent (testver connect) on your machine opens an outbound WebSocket to the Testver server. The server-side Playwright adapter is replaced for your user with a LocalBrowserAdapter that proxies every command (launch, goto, click, screenshot, …) over that WebSocket to the agent. The agent runs the command against a real Playwright Browser locally and ships back results — including a continuous video screencast and Page mirror so the UI’s LiveBrowserView feels native.

Key properties:

• Outbound-only. Your machine connects out to Testver. No inbound port, no firewall changes.
• Bound to your user. The token issued for the agent ties it to your account; nobody else can route through your machine.
• Multi-tab safe. Multiple Testver tabs (different recordings, AI chats) all share the same connector — they multiplex over the one WebSocket.
• Auto-fallback. If your connector goes offline, new tool calls fall back to server-side Playwright. When it comes back, they route to local again. Existing per-tab browser sessions don’t switch mid-flight; close them in Browser Sessions to restart fresh on the now-active connector.

Set it up

1. Generate a connector token

In Testver:

1. Open Settings → look for the Local Browser Connector card.
2. Click the key icon (or “Issue token” button).
3. A one-time token + connect command appears. Copy them.
4. The token banner shows a count of currently-active tokens — you can revoke any from the same modal.

Tokens are:

• Single-use for connection — once an agent connects with it, the token is marked consumed.
• Tied to the user that issued them. Only that user can revoke them later.
• Time-limited — expire after a configurable window if not consumed.

2. Run the agent

On your machine:

testver connect <paste-the-command>

The agent will:

• Open the WebSocket to your Testver server.
• Register itself in the Connector Registry.
• Print a status line and a tail of routed commands.

Leave the terminal running. Closing it disconnects the connector.

3. Confirm it’s live

Back in the Testver UI:

• The Local Browser Connector card flips to “Connected” with the agent’s machine name and OS.
• Settings → Browser Sessions now shows a Local row for your user the moment any tab uses a browser.
• Open AI Record or AI Assistant — the next browser launch happens on your machine.

What runs locally vs on the server

Action	Where it runs
AI Assistant LLM call	Server (or your configured provider)
File reads/writes, run-command, git ops	Server / project filesystem
Browser launch & navigation	Your machine (when connector active)
Click, type, screenshot, evaluate	Your machine
AI Record action capture	Your machine’s browser
Live screencast frames	Captured locally, streamed to the UI

In other words: your machine drives the browser, the server orchestrates everything else.

Live preview & reverse input

The agent captures the page as a video stream (Chromium CDP screencast, or polling fallback for Firefox/WebKit) and pushes frames over the same WebSocket. Mouse, keyboard, and scroll events from the LiveBrowserView in the UI travel back the other way and are replayed on the local Playwright page. The end result is indistinguishable from the server-side experience — including click-to-inspect during AI Record.

Browser engines

The agent uses the Playwright build installed on your machine. To make Firefox / WebKit available locally:

npx playwright install firefox
npx playwright install webkit

The UI lets you pick the engine per-launch in the same dropdown you’d use for the server-side path.

Multiple users, multiple connectors

In a multi-user Testver install:

• Each user can register one active connector at a time (newest replaces previous; the old one is rejected with a clean shutdown reason).
• User A’s commands go only to User A’s connector — never to User B’s. Tokens carry the user identity; routing is per-user end-to-end.
• The Connector Registry’s auto-refresh hook flips per-tab BrowserManagers when you register or disconnect, so you don’t have to refresh the UI to switch between server-side and local routing.

Security

• Tokens are credentials — treat them like API keys. Don’t paste them into shared chats.
• The token modal lets you revoke any active token; revoking disconnects the agent immediately.
• The agent only accepts commands from the Testver server it connected to. There’s no inbound listener on your machine.
• Audit log records token issuance, revocation, and connector register/evict events.

Troubleshooting

The card stays on “Disconnected” after running testver connect

• Check the agent terminal for connection errors.
• Verify your Testver server URL is reachable from your machine.
• If you’re behind a corporate proxy, set HTTPS_PROXY before running the agent.

Screencast freezes mid-recording

• The agent will reconnect automatically on transient drops. If it stays frozen, find your row in Browser Sessions and close it — the next launch starts a fresh local browser.

“Session closed by admin/user” in the agent log

• An admin or you closed the local-connector row from Browser Sessions. Re-run testver connect to register again.

Token banner still showing after I closed the modal

• Banners auto-dismiss when the token is either consumed by an agent or revoked. If it’s stale, revoke from the modal — banner clears immediately.

Related

• Settings → Browser Sessions — see and close active local-connector sessions.
• AI Record — recordings transparently use your local browser when a connector is active.
• AI Assistant — Web mode browser tools route to your local browser.
• Connectors — external service integrations (JIRA, Slack, etc.).