browser-harness review of browser control and error handling
Testing browser-harness 0.1.13 with local forms, uploads, retained state, tab switching and recovery, including an MCP result-format detail that hosts must handle.
AgentIndex · Published 2026-11-04 · Updated 2026-11-04
browser-harness gives coding agents a browser control layer through the Chrome DevTools Protocol, or CDP. It exposes operations such as clicking, typing, reading pages and uploading files. Its typical proposition is to reuse an existing browser session, including work a person has already done to sign in.
Choosing it starts with two questions: which browser state the task needs, and whether the host can distinguish successful actions from failed ones. Our controlled check completed basic interactions and exposed an integration detail: some failures are represented inside JSON content even when the outer MCP result says isError: false.
An isolated browser for this check
On 2026-11-04, we installed browser-harness[mcp]==0.1.13 in a separate Python environment and called its MCP entry point with MCP TypeScript client 2.4.0. We provided the CDP address of a newly launched headless Chrome 156 profile. It visited only our local synthetic page.
This checks the control path. It does not reproduce first-time permission prompts in a person's normal Chrome, or establish behavior for a particular site's login, CAPTCHA, payment flow or long-running task. We did not run an autonomous model or compare competing agents.
Eight functional checks
The page had a name field, a save button, a file input and visible output areas. Saving wrote the name to that fixture site's localStorage, allowing a reload check.
| Check | Observed result |
|---|---|
| Initialization and discovery | Connected and listed 23 tools |
| Open and inspect the local page | Expected title and URL |
| Fill a field and click by coordinates | Output became Saved: AgentIndex |
| Upload a local text file | Page displayed the selected fixture filename |
| Reload the page | Name field recovered AgentIndex |
| Switch and close tabs | Switched between two owned tabs and closed the test tab |
| Fill a nonexistent field | JSON error returned; subsequent inspection still worked |
| Save a screenshot | Readable 756 × 494 PNG |
Reload persistence establishes localStorage behavior for this page, rather than reliable authentication for every website. The upload check covered an ordinary file input; it did not cover drag-and-drop widgets or multipart upload workflows.
The reproducible fixture contains the page, verifier and results. Default recording and telemetry were disabled. The screenshot was an explicit test of our artificial page.
Parse errors inside the tool content
The missing-selector call produced a text block containing a JSON object with an error field. Its outer MCP isError value was false. A subsequent page-information call succeeded, so the failure did not terminate the service. This matches the project's documented approach of returning error JSON while keeping the process running. MCP interface documentation
A host that treats a completed request as a completed task could incorrectly record that input as successful. It should parse the content, check the error field and verify a page-level outcome. Our fixture checked the saved result text and uploaded filename instead of relying on transport success.
Recovery also depends on what an action may have done already. Reading a page can usually be repeated; sending a message or submitting an application needs an outcome check before another attempt. Host logic must implement that distinction. The tool's error format cannot define the completion criteria of every business workflow.
Connection scope affects the operating model
The documented default connects to a running Chrome instance with remote-debugging authorization. That grants access at the browser-instance level, rather than exposing one business action in isolation. Select the browser profile and account scope according to the actual task. Project and connection model
For a task confined to one internal application, a dedicated work profile is a useful first trial. Repeatable CI checks benefit from a clean, rebuildable browser baseline. Reusing a personal session may reduce repeated sign-ins, but makes results depend on its cookies, extensions, current pages and account permissions.
Our machine also showed why connection diagnostics matter. Its proxy configuration initially sent the local WebSocket handshake toward SOCKS and the connection failed. Excluding loopback addresses from the proxy in the test processes allowed the same package to connect. This was an environment prerequisite, not evidence of a universal project defect. Keep the endpoint and diagnostic output so connection failures do not get confused with failed page actions.
Reusable helpers still require code review
The project lets an agent place missing task helpers in a local workspace and reuse that executable code later. That is persistence of helpers and working state; it does not establish that the model trained itself or will automatically succeed on every similar site. Installation and workspace documentation
Review those helpers like other automation scripts. Identify their page assumptions, failure behavior and any account-specific constants. Our check used existing MCP tools and did not assess the quality of agent-generated helpers.
A useful first deployment
Start with a reversible flow whose outcome is visible, such as filling an internal draft and stopping before submission. Define completion, check the effects of page changes, and exercise recovery before extending the task.
If the main goal is reliable testing of your own web application, compare the team's existing Playwright tests or another reproducible browser environment as well. The project's published comparisons have specific host, cloud-browser and task-set conditions. This review establishes basic control and error-handling behavior, without ranking overall agent performance.
Related reviews: MCP SDK contracts and migration, Next AI Draw.io browser rendering.