Easy UI

It exposes 26 tools built on Playwright over HTTP/SSE. Claude Code decides what to click; the server only performs each action, logs it, and writes the report when the session ends. No test scripts to write, and no LLM runs inside the container.

The reports directory is volume-mounted, so the JSON and HTML land in ./reports/ on your machine. A thin REST wrapper (POST /api/run-test) covers callers that cannot speak MCP.

The container runs with network_mode: host in docker-compose.yml, not a published port on a bridge network. This is required: the browser Playwright drives inside the container must reach localhost:<port> on your host machine, where the dev server of the app you are testing runs. On a default bridge network the container has no route back to the host, so targets such as http://localhost:8766 hang or fail with ERR_CONNECTION_REFUSED, and http://<host-LAN-IP>:8766 will just time out, even if the target server is listening and reachable via curl from the host shell.

Where network_mode: host is not available (for example Docker Desktop on macOS or Windows), use host.docker.internal as the hostname instead of localhost when calling ui_navigate, and add this to docker-compose.yml:

extra_hosts:
  - "host.docker.internal:host-gateway"

As one line: extra_hosts: ["host.docker.internal:host-gateway"].

Label your steps

ui_step(label) groups everything that follows under a plain-language heading until the next ui_step. The label is the report's only caller-authored statement of intent. A session with no ui_step calls still renders, under one implicit group.

ui_start_session  target: "Account Access toggle smoke"
ui_step           label:  "Open the Settings page"
ui_navigate       ...
ui_wait_for       ...
ui_step           label:  "Turn Manual Invoice access on"
ui_click          ...
ui_assert         ...
ui_end_session

Use the refs from page state

ui_get_page_state returns the page as short text: one line per visible interactive element, @eN role "name", with its non-default state. Pass the ref as the selector of any tool instead of guessing a CSS selector. A ref means the latest snapshot of that page and follows the element that was listed: if that element is gone or replaced, the call fails and says to call ui_get_page_state again, and it never acts on a different element. Reports show the real selector of each action; a refused ref is a soft step that does not fail the session. format: "full" returns the JSON with a verified selector per element instead, and no refs.

url: https://shop.example/login
title: Sign in
@e1 textbox "Email" required
@e2 button "Sign in" disabled
ui_click  selector: @e2

Page state also reports what the page looks like right now. An element line carries only its non-default state (disabled, checked, value, expanded, selected, pressed, required, invalid; a password value is never shown). overlay @o1 lines list each open dialog topmost first and are absent when none is open. focused: names the element holding focus. Custom widgets such as comboboxes, switches and rich-text editors are listed too. To read text, call ui_get_text.

One connection can hold several open sessions (up to 3; set MAX_SESSIONS_PER_CONNECTION to change it), for example to compare two URLs or a logged-in and a logged-out user. ui_start_session returns a session id; pass it as session_id to any other tool to choose the session it acts on. Each session has its own browser, page, step label and report.

ui_start_session  target: "staging"      -> Session <id-A> started
ui_start_session  target: "production"   -> Session <id-B> started
ui_navigate       url: ...  session_id: <id-A>
ui_navigate       url: ...  session_id: <id-B>
ui_end_session    session_id: <id-A>
ui_end_session    session_id: <id-B>

With exactly one open session session_id can be left out. With several open, leaving it out is an error that lists the open ids, so a call never lands on the wrong page. A session is reachable only from the connection that started it. Another connection passing its id gets Unknown session. A session with no tool call for 10 minutes (SESSION_TIMEOUT_MS, in milliseconds) is closed automatically: its browser is shut down and its report is written with status timed_out. A call with that id then returns Session <id> was closed after 10 min idle. When a connection closes, every session it still owns is ended and reported.

Before you click, ask the page what it looks like right now. ui_get_page_state lists up to 200 visible interactive elements, each with an @eN ref and, when it differs from the default, its state. A ref is valid for the latest snapshot only and fails, rather than misfires, once the page has changed; format: "full" returns JSON with a verified selector per element and no refs. On a long page, viewport: true lists only what is on screen and within only what is inside one element; a scoped reply says how many elements it left out. Custom widgets are included: combobox, listbox, option, switch, slider, spinbutton, searchbox, treeitem, summary, contenteditable regions, and anything with a role and tabindex >= 0.

overlay @o1 dialog "Confirm" modal lists each open dialog, topmost first, and its ref works wherever a selector does (for example ui_click_outside). No overlay line means nothing is open, so a modal opening or closing shows up as the line appearing or disappearing. focused: @e2 names the element holding focus, and is absent when focus is on the page body, in an iframe or in a shadow root.

ui_get_text reads text: the trimmed visible text of one element, or of the whole page body with no selector, cut at 4000 characters with a note of the real length. It fails on 0 or more than 1 match and on an element that is not visible. The text it reads is returned to you but not stored in the report.

The reply in detail

ui_get_page_state returns the page as short text: a url: line, a title: line, then one line per visible interactive element (up to 200) as @eN role "name" followed by its non-default state, and messages: (visible alert/status text such as validation errors). Pass the ref as the selector of ui_click, ui_fill, ui_select_option, ui_press_key, ui_hover, ui_set_checked, ui_scroll, ui_get_text, ui_take_screenshot and ui_upload_file (and as from / to of ui_drag, container of ui_scroll, within of ui_get_page_state) instead of guessing a CSS selector.

A ref means the latest snapshot of that page and nothing older. A compact snapshot does no selector work; the selector behind a ref is built and checked against the live page when you first use the ref. A ref follows the element that was listed: if that element is gone or replaced by a look-alike, the call fails with a message that names the ref and says to call ui_get_page_state again. It never acts on a different element, and nothing is clicked or typed. A ref from another session or tab, one used before any snapshot, and an unknown number fail the same way. Reports and the action log show the real selector of each successful action. A refused ref is listed as a soft failed step with the ref the agent tried; it does not fail the session or take a failure screenshot. CSS and Playwright selectors still work everywhere; elements without an accessible name are not listed, so reach those with a CSS selector.

format: "full" returns the earlier JSON instead: the elements as {role, name, selector, state?} with a selector checked against the live page, plus overlays, focused and messages. It has no refs, and taking it ends the refs of the previous snapshot. A selector containing nth= is positional: call ui_get_page_state again after the page changes before reusing it.

Page state also tells you what the page looks like right now, so you do not have to guess:

• An element line carries only its non-default state, as key for true and key=value otherwise: disabled, checked (checked, checked=false or checked="mixed"), value="..." (inputs, textarea, select; cut at 100 characters; never shown for a password field), expanded, selected, pressed, required, invalid. Names are quoted JSON strings, so a quote or a line break in a name cannot make a second line.
• Custom widgets are listed too: combobox, listbox, option, switch, slider, spinbutton, searchbox, treeitem, menuitemcheckbox/menuitemradio, summary, contenteditable regions, and anything with a role and tabindex >= 0.
• overlay @o1 dialog "Confirm" modal lists each open dialog, topmost first (role=dialog, alertdialog, dialog[open], aria-modal); @o1 is accepted wherever a selector is, for example by ui_click_outside. No overlay line means nothing is open, so a modal opening or closing shows up as the line appearing or disappearing.
• focused: @e2 names the element holding focus (as role "name" when it is not in the list). It is absent when focus is on the page body, in an iframe or in a shadow root.
• note: appears when the list was cut at 200 elements (it then suggests viewport and within), or when you scoped the list and it left elements out.

To read less on a long page, scope the list. Both arguments are optional and off by default, so with neither the reply is exactly as described above.

• viewport: true lists only elements whose bounding box is at least partly on screen at the current scroll position.
• within (a selector or an @eN / @oN ref) lists only the elements inside that one element; it fails, listing nothing, if it matches no element or several. An element with nothing interactive inside gives an empty list, not an error.
• Pass both and an element must satisfy both. overlays, focused and messages are never scoped. Refs number the scoped list and work as usual.
• A scoped reply that left elements out says so, for example note: Showing 37 of 180 elements (viewport only); scroll, or call without viewport, for the rest. The 200-element cap applies after scoping, and its note can follow on the same line.

Click outside

ui_click_outside(selector) clicks just outside the element you name (pass the modal panel, not the backdrop) and says what it hit, the way a user dismisses a modal by clicking its backdrop. If nothing safe exists around it, it fails and suggests ui_press_key with Escape.

ui_click also takes optional button (right fires contextmenu), clickCount (2 = double-click), modifiers (for example ["Shift"]), position (an offset inside the element) and force (click through a covering element). Without them it is a plain left click.

Native dialogs

A browser alert, confirm, prompt or beforeunload blocks the page, so the server holds it open and asks you. The call that opened it returns at once with Browser is waiting on a confirm dialog: "Delete?". Every other tool is refused until you answer with ui_dialog (accept or dismiss, plus text for a prompt); its reply tells you what the interrupted action did next.

Calling ui_dialog when nothing is waiting pre-sets the answer for the next dialog, which is then answered without pausing: use it in scripted flows. A dialog left unanswered for DIALOG_TIMEOUT_MS (default 120000) is dismissed and the next response says so. Every dialog is logged in the report with who answered it.

ui_start_session takes optional device (a Playwright device name such as "iPhone 13": mobile user agent, touch, pixel ratio, size), viewport {width, height} (overrides the device size), colorScheme (light or dark), locale and timezoneId. An unknown device is an error that lists the valid names. With none of them the browser is a 1280x720 desktop. They apply to that session only, and appear in the report header. ui_set_viewport(width, height) resizes mid-flow (320-3840 by 320-2160); layouts can change, so call ui_get_page_state again afterwards.

ui_fill sets the whole value at once. ui_type(selector, text, delayMs?) types key by key (keydown, input and keyup per character, appended to what is there), for autocomplete, search-as-you-type, masked inputs and OTP boxes. The report only says how many characters were typed. The text itself is replaced by •••• (in the reply and the stored step) when the target is a password, one-time-code or card-number (autocomplete) field, or uses -webkit-text-security.

ui_navigate_history(action) with back, forward or reload keeps the history and form state that a second ui_navigate would lose. ui_scroll also takes container (a scroll area such as a chat panel or virtual table) and direction (down, up, left, right, top, bottom), moves one step per call and says when the end is reached, so a loop over a lazy list knows when to stop.

ui_take_screenshot also takes selector (just that element), fullPage (the whole page, cut at 16000 device pixels tall and 3840px wide) and inline: true, which returns the PNG as image content (scaled to fit 1280x8000px) as well as writing it to reports/.

ui_type             selector: "[name=\"city\"]"  text: "Han"  delayMs: 50
ui_navigate_history action: "reload"
ui_take_screenshot  selector: "[role=\"dialog\"]"  inline: true

ui_get_logs reads the browser problems captured so far while the flow runs: console errors, uncaught page errors, failed requests and HTTP 4xx/5xx responses (method and URL, never bodies or headers). since: last (default) returns only what is new, start returns everything, and level: warning adds console warnings. Repeats are grouped as ×N, at most 50 lines per call. Use it when an action seemed to do nothing.

A target=_blank link or window.open popup opens a tab the session tracks: the next response says New tab opened: <url> (tab 2), but the session does not switch to it. ui_tabs with list, switch or close moves between tabs (numbered from 1), and every other tool acts on the current tab.

ui_upload_file(selector) uploads one built-in file, default_draft.png (a tiny PNG), to a file input or to the chooser a button opens. It takes no path, so no other file in the container can be sent to the site under test. ui_drag(from, to) drags one element onto another, for HTML5 drag-and-drop and pointer-based sortables.

Downloads are saved to reports/downloads/<session>/, logged as an action and announced on the next response (Downloaded: <name> (<bytes> bytes)). A session keeps at most 20 downloads of up to 25 MB each; a download over either cap is discarded and the next response says so (once, for the count cap). Tabs, logs and downloads exist only inside a ui_start_session bracket and belong to one session: with several open, pass session_id.

ui_upload_file    selector: "input[type=file]"
ui_drag           from: "[data-testid=\"card-1\"]"  to: "[data-testid=\"column-done\"]"

That is the UTC start time, a readable slug of the session target, and the first 8 characters of the session id. reports/index.html lists the sessions, newest first and capped at 500 (older reports stay on disk, unlisted), and is rewritten after every report.

An HTML report shows a verdict box (status, target, step, action and failure counts, and duration); the run as labelled steps, with per-step outcomes and elapsed time; browser problems (console errors, uncaught page errors and network-level request failures, captured automatically and never changing the verdict, up to 50 per session); and the raw action log, collapsed behind a disclosure.

HTTP 4xx/5xx responses (a 500 is a successful request to Playwright, so requestfailed never fires) are captured as httperror as <status> <METHOD> <url>, with the query string dropped because it may hold tokens. Auto-failure screenshots are budgeted per session (FAILURE_SCREENSHOT_BUDGET, default 3), and identical screenshot content is embedded only once.

POST /api/run-test runs one navigate-and-screenshot test and returns a report.

The response is JSON with status (passed, failed or timeout), report_url, screenshots and logs. report_url is a path inside the container: read the report from the host under ./reports/ using its basename. GET /health returns {"status":"ok"}.

A single test file can be run on its own:

$ node --import tsx --test test/<file>.test.ts

This page is plain static HTML in site/index.html. Vercel serves the site/ directory as-is, with no install and no build (see vercel.json).