attach
Attach to existing browser session
LABSCO SUMMARY
Browser control and report forensics in the same tool list, and the second half is the rarer one.
The driving half is unremarkable in a good way — actions take accessible-name locators alongside selector, and snapshot trims the DOM by default while telling you what it dropped — but test-results, inspect-result, time-travel-snapshot and time-travel-export-html are the part that is hard to find elsewhere, reading a finished report and replaying an rrweb capture at a chosen time with a diff against an earlier one. Two constraints to know going in: console is documented as working with Chromium-based browsers, and automatic browser download covers Chrome and Firefox, so anything else needs a driver you start yourself and hand over as gridUrl.
What it is
A Testplane-backed browser control and report-reading server with 24 tools: interaction against a live browser, DOM snapshots and console output, tab and session management, arbitrary Testplane script execution, and reading Time Travel rrweb snapshots out of an HTML report.
What you get
- Elements addressed the way a test would address them: click, hover, type and select each take role, name, labelText, placeholderText, altText, title, testId, displayValue, text and selector, with exact and hidden controlling the match, so an action can be written against the accessible name instead of a CSS path.
- Waiting expressed as a condition rather than a sleep: wait blocks on an element appearing or, with disappear, on it going away, under timeout, and can fold a snapshot into the response via includeSnapshotInResponse.
- A DOM snapshot tuned for reading: snapshot drops noisy tags and attributes by default and reports what it omitted, with includeTags, excludeTags, includeAttrs, excludeAttrs, maxTextLength and truncateText available when the default hides what you need.
- Console messages without the repeats: console returns browser-side messages that were not already returned earlier in the session, documented as working with Chromium-based browsers.
- Tabs as first-class state: list-tabs returns every open tab with URL, title and active status, while new-tab, switch-tab and close-tab work by 1-based tab number.
- Sessions you can join rather than only create: launch takes desiredCapabilities, gridUrl, headless and windowSize, attach joins an existing session, attach-repl connects to a running Testplane REPL by host and port, and close-browser ends the session.
- Browser state saved and restored as a file: save-state writes cookies, localStorage and sessionStorage to JSON, and restore-state reads it back, refreshing the page by default so the restored state is actually observed.
- An escape hatch that stays inside the framework: run-code takes inline code or a file and runs it against the current browser, receiving browser as its only argument.
- Report reading, not only report generation: test-results lists final-attempt results from a Testplane HTML report filtered by grep, grepError, status, browser, duration, meta, fields, limit and offset, and inspect-result returns one attempt as JSON.
- Replay at a chosen moment: time-travel-snapshot returns the DOM of an rrweb snapshot at a given time with an optional diff from an earlier one, and time-travel-export-html writes that moment out as a browser-openable HTML file with inline styles.
Requirements
No account and no key. What has to be present is a browser Testplane can drive — Chrome and Firefox are documented as downloaded automatically, and anything else requires a driver you already have running, passed as gridUrl. The report tools need a Testplane HTML report on disk, and time-travel-snapshot and time-travel-export-html need a Time Travel rrweb snapshot inside it.
Setup effort
One command — npx -y @testplane/mcp
USE CASES
01
Reproducing a bug a user described
Open the page, act on it by the labels and roles a person would see, and take a trimmed DOM snapshot at the point where it goes wrong.
02
Finding out why a click did nothing
Wait for the element that should have appeared, read the console messages you have not seen yet, and snapshot the DOM to see what is actually there.
03
Replaying the moment a test failed
Filter the report down to the failing test, inspect the attempt as JSON, then pull the replayed DOM at a chosen time with a diff against an earlier point.
04
Handing a failure to someone without the toolchain
Export the replayed moment as a standalone HTML file with its styles inlined, and attach a viewport screenshot when the difference is visual.
05
Testing a flow that depends on being logged in
Save the cookies and web storage once, restore them on the next run so the page comes up authenticated, and carry on from there.
06
Driving a browser this server cannot download
Start your own driver, point the session at it as a grid URL with the capabilities you need, or attach to a session that is already running.
24 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
attach-repl
Attach to a running Testplane REPL session
click
Click an element on the page.
close-browser
Close the current browser session
close-tab
Close a specific browser tab by its number (1-based), or close the current tab if no number is provided
console
Get browser-side console messages. This command only works with Chromium-based browsers and returns only "unseen" messages - those that were not returned by the previous getLogs call in the current session.
hover
Hover an element on the page.
inspect-result
Read a Testplane HTML report and inspect test result attempt details as JSON
launch
Launch a new browser session with custom desired capabilities. Avoid using this tool unless the user explicitly requests a custom browser configuration; browsers are launched automatically for commands like navigate to URL. Testplane can ONLY download Chrome and Firefox automatically, for other browsers you MUST ensure that driver is launched and provide it as custom gridUrl.
list-tabs
Get a list of all currently opened browser tabs with their URLs, titles, and active status
navigate
Open a URL in the browser
new-tab
Open a new browser tab, optionally navigate to a URL, and automatically switch to it
restore-state
Restore browser state from a JSON file. By default the page is refreshed after restore so it can observe restored cookies and web storage.
run-code
Run arbitrary Testplane script using the current browser, useful when other tools don't provide the functionality you need. Inline input may be code or a function that receives browser as its only argument. In REPL sessions, the code is passed directly to the Testplane REPL.
save-state
Save the current browser state, including cookies and web storage, to a JSON file
screenshot
Capture a PNG screenshot of the current browser viewport. Strongly prefer capturing text-based snapshots using takePageSnapshot tool. Only use to test for visual changes when text-based snapshots are not useful.
select
Select an option in a native <select> element.
snapshot
Capture a DOM snapshot of the current page. Note: by default, not useful tags and attributes are excluded (e.g. script, style, etc.). Prefer to use defaults. Response contains info as to what was omitted. If you need more info, request a snapshot with more tags and attributes.
switch-tab
Switch to a specific browser tab by its number (starting from 1)
test-results
Read a Testplane HTML report and list final-attempt test results with filters
time-travel-export-html
Export a Testplane Time Travel rrweb snapshot at a selected time as a browser-openable HTML file with captured inline styles
time-travel-snapshot
Inspect Testplane Time Travel rrweb snapshot at a selected time and return a DOM snapshot of the replayed page, optionally with a diff from a previous time
type
Type text into an element on the page.
wait
Wait for an element to appear or disappear on the page. Useful for waiting until page loads fully or loading spinners disappear.
BEFORE YOU INSTALL
What to know first
Tools you get
24 tools when we connected.
Requires
npx on PATH
CONTEXT COST
Moderate Standing cost
Rated by the size of the 24 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Add the block to your client, or run the command directly.
Server setup
Configuration file
JSON
{
"mcpServers": {
"testplane": {
"command": "npx",
"args": [
"-y",
"@testplane/mcp"
]
}
}
}npx
TERMINAL
npx -y @testplane/mcp
