browser
Idempotent
Render a URL in headless Chromium to capture a visual screenshot, console logs, errors, and page metadata for UI testing and verification.
Instructions
Render a URL in headless Chromium and SEE it: returns a WebP screenshot the model can view, plus console output, uncaught JS errors, failed requests, optional performance metrics, and page metadata. Use this (not web, which is HTTP-only) for the VISUAL result or client-side JS behavior — verifying a local dev UI (http://localhost:3000) after a change. Write & run a UI test: outline=true lists the interactive elements with ready-to-use selectors, then actions clicks/fills/asserts through the flow (pass/fail reported). WordPress admin: recipe=wp_login|wp_admin|wp_plugins|wp_posts|wp_new_post + site= fills login from encrypted/env secrets (never logged) and waits for #wpadminbar (plugins/posts navigate after). Session reuse: session= keeps cookies across browser calls in this MCP process. Responsive check: device=mobile|tablet|desktop, or devices=["all"] to capture every viewport in one call. Performance check: metrics=true (FCP, load, request count, page weight). Watch it happen: headed=true opens a visible browser that highlights each click/input. Lean by default — the opt-in outline is bounded, not a full-DOM dump. Loopback always allowed; set allow_private for LAN. Needs the managed browser: if missing, run ch browser install once. Binary must be built with -tags rod (default codehelper update / install.sh).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gui | No | Alias for headed=true (visible Chromium). | |
| url | No | URL to open (e.g. http://localhost:3000). Optional when site= is set — then the site login/admin URL is used. | |
| repo | No | Repository name for site/secret resolution (optional; defaults to current MCP workspace) | |
| site | No | Connections website profile name (codehelper connections add-site). Supplies base URL + user; password from env:/secret store only — never pass passwords in MCP args. | |
| audit | No | Accessibility + Core Web Vitals audit. 'lite' = fast built-in checks (missing alt/labels/accessible-names, page lang/title); 'full' = the axe-core engine (comprehensive, with impact levels — needs `ch browser install`). Both also report LCP/CLS/FCP/TTFB with good/poor verdicts. | |
| split | No | Capture the full page split into vertical pieces (~2000px each), returned as multiple images at full resolution — read a long page without the downscaling a single tall screenshot suffers | |
| trace | No | Include a compact timing trail (navigate/action/wait/heal/fail) for debugging flaky flows — not a CDP file. | |
| width | No | Override viewport width px (else from device) | |
| clip_y | No | Capture only a region starting at this Y offset (CSS px); pair with clip_height | |
| device | No | Viewport preset: desktop (1280x800, default) | tablet (768x1024) | mobile (390x844). Sets size, pixel ratio, mobile emulation, and UA. | |
| format | No | Screenshot format: webp (default, smallest) | png | jpeg | |
| headed | No | Run a VISIBLE browser (default headless) so a human can WATCH the agent drive the page: each action flashes a labelled box on its target element and SlowMotion paces the clicks/inputs. Needs a graphical display (skip over SSH/CI — or use xvfb-run). Alias: gui=true. Env CODEHELPER_BROWSER_HEADED=1 or project browser_headed sets the default. | |
| height | No | Override viewport height px (else from device) | |
| recipe | No | Named interaction recipe prepended before actions: wp_login | wp_admin | wp_plugins | wp_posts | wp_new_post | laravel_login | django_admin | drupal_login | magento_login | spa_hydrate. Requires site=. When omitted with site=, uses site kind / project browser_recipe default. | |
| actions | No | Interaction + test steps before the screenshot. Locators: selector CSS, testid:/role:button:Name/text:/name:/ref:e3 prefixes, or fields role/name/testid/ref. Actions: click|type|fill|select|hover|press|scroll|wait|wait_idle|wait_hydrate|navigate|wait_nav|assert|assert_text|upload|snapshot|storage_set|storage_get|storage_clear|clear_cookies. Example: [{"action":"click","selector":"ref:e3"},{"action":"assert_text","selector":".ok","text":"Thanks"}]. Stops at first failure; failure_pack + screenshot always attached. Tip: outline/snapshot first; session= for login cookies. | |
| devices | No | Capture several viewports in one call, e.g. ["mobile","desktop"] or ["all"]. Overrides `device`. Returns one image per device. | |
| metrics | No | Collect performance metrics: FCP, DOMContentLoaded, load, request count, transfer KB, JS heap | |
| outline | No | Return a compact map of the page's INTERACTIVE elements (inputs, buttons, links, form controls) — each with a stable ref (e1,e2,…), ready-to-use CSS selector, role, accessible name, input type, placeholder and value. Use this FIRST to discover targets; drive them with selector=ref:e3 or ref="e3". Bounded (≤100 elements), not a full-DOM dump. | |
| quality | No | Compression quality 1-100 for webp/jpeg (default 80) | |
| session | No | Named in-process cookie jar. Captures sharing the same session reuse auth cookies (e.g. wp_login then open plugins without re-login). Lives for the MCP server process lifetime. | |
| slow_mo | No | Headed only: delay in ms before each action so clicks/inputs are perceptible (default ~650ms). Ignored in headless. | |
| wait_ms | No | Extra fixed wait after load, in milliseconds (with wait_hydrate: overall hydrate timeout) | |
| baseline | No | Visual regression: name a baseline. First call saves the screenshot; later calls return a diff image (changed pixels in red) + % changed. Per-device baselines. | |
| selector | No | Screenshot only this CSS-selected element | |
| snapshot | No | Return a bounded ARIA/role snapshot (Playwright-MCP style: role "name" lines, ≤80 nodes). Prefer over dumping HTML. Use with role/name/testid locators in actions. | |
| full_page | No | Capture the full scrollable page, not just the viewport | |
| clip_height | No | Height (CSS px) of the clipped region to capture at full width | |
| timeout_sec | No | Overall timeout seconds (default 30) | |
| upload_allow | No | Extra upload sandbox roots (os path-list separator). Upload paths must live under the workspace repo root and/or these dirs (also CODEHELPER_BROWSER_UPLOAD_ALLOW). Multi-file: text= path1||path2 or newlines. | |
| wait_hydrate | No | After load, wait for network idle + DOM stable (SPA/React/Vue/Next and WP admin hydration). Pair with wait_selector for a ready landmark (#root, #wpadminbar, …). | |
| allow_private | No | Permit private/LAN (RFC1918) targets; loopback always allowed, cloud-metadata/link-local always blocked (default false) | |
| pause_on_fail | No | Headed only: keep the window open ~3s after a failed step so a human can see the failure. Env CODEHELPER_BROWSER_PAUSE_ON_FAIL=1. | |
| session_clear | No | Clear the named session cookie jar before this capture | |
| wait_selector | No | Wait for this CSS selector to appear before capturing (also used as hydrate landmark when wait_hydrate=true) | |
| debug_pack_dir | No | On action/assert failure, write a debug pack (failure screenshot + report.json with console errors, failed network, outline/snapshot, URL, action log) to this directory. Default: ~/.codehelper/browser/debug-packs/<timestamp>/. | |
| segment_height | No | Max height (CSS px) per piece when splitting a full-page capture (implies split+full_page) | |
| preview_actions | No | Return a viewport screenshot after each interaction step (before the final capture). Requires `ch config browser set --action-previews on` (disabled by default). Failed steps always attach a shot even when this is off. | |
| update_baseline | No | Overwrite the named baseline with the current screenshot instead of diffing | |
| pause_on_fail_ms | No | Headed + pause_on_fail: override pause duration in ms (default 3000). |