Browser Interaction Tools
Testronaut agents use Playwright-backed tools to interact with the browser. Most missions should describe the user goal and expected result rather than prescribe every tool call. Name a tool explicitly when the interaction itself is under test or when the agent needs help with an unusual control.
Keyboard inputβ
Use press_key when a journey depends on a keyboard action such as submitting a
form with Enter, dismissing a dialog with Escape, or invoking a shortcut.
Fill the access-code field, then use press_key with key "Enter" and selector
"#access". Confirm that the dashboard appears.
The tool accepts:
| Argument | Required | Description |
|---|---|---|
key | Yes | A Playwright key or shortcut such as Enter, Escape, Tab, Control+B, or Meta+B. |
selector | No | A CSS selector to focus before pressing the key. |
For platform-specific shortcuts, use Control on Windows/Linux and Meta for
Command on macOS. The selector is especially useful for Enter because it makes
the intended form control explicit.
Open the report dialog. Use press_key with key "Escape", then confirm that the
dialog is no longer visible.
press_key currently has no frame argument. Its optional selector resolves on
the active page, so use the frame-aware tools below when an element is inside an
iframe.
Iframe interactionsβ
For controls inside an iframe, provide the iframe's CSS selector through the
optional frame argument on fill or click.
Inside iframe#ship-map-frame, fill #navigator-call-sign with "Nova".
Still inside that iframe, click #lock-route and confirm that the route is locked.
This corresponds to interactions shaped like:
{ "selector": "#navigator-call-sign", "text": "Nova", "frame": "iframe#ship-map-frame" }
{ "selector": "#lock-route", "frame": "iframe#ship-map-frame" }
Visible-text checks search iframe documents by default. The check_text tool's
searchAllFrames option defaults to true; set it to false only when a check
must be restricted to the main document.
Browser-native JavaScript dialogsβ
JavaScript alert(), confirm(), prompt(), and beforeunload dialogs block
the browser action that opened them. When the response matters to the test,
describe it explicitly in the mission and have the agent call
prepare_dialog_response immediately before the click, reload, or navigation
that triggers the dialog.
Arm an exact confirm response for "Emergency meeting! Attend?" with action
"accept", then click "Request attendance". Verify that the page reports
"Attendance confirmed. Not sus."
The response is one-time and expires after 10 seconds by default. It supports:
type:alert,confirm,prompt, orbeforeunload(required)action:acceptordismiss(required)messagefor an exact match, ormessageIncludesfor a substring matchinputonly when accepting aprompttimeoutMsfrom 250 to 30,000 milliseconds
Use a message constraint when the text is stable. It prevents a prepared accept from being applied to a different, unexpected dialog. An unexpected or nonmatching dialog is dismissed fail-closed so execution does not hang. The prepared rule remains available until it matches or expires.
Mission reports record the dialog type, message, default prompt value, page URL, whether the response rule matched, the chosen action, and the response outcome. Expired response rules are recorded as timeouts. Always assert the resulting page state as well; accepting a dialog only proves that the browser received the response, not that the application produced the intended result.
For beforeunload, browsers control the displayed message, so match on the
beforeunload type rather than application-supplied text. Accepting permits
the navigation; dismissing keeps the current page open.
Common interaction toolsβ
| Tool | Use it for | Important arguments |
|---|---|---|
fill | Entering text into an editable field | selector, text, optional frame |
click | Activating a control by selector | selector, optional frame |
click_text | Activating a control by its visible text | text |
press_key | Keys and keyboard shortcuts | key, optional selector |
check_text | Confirming visible text | text, optional searchAllFrames |
Runnable examplesβ
The official examples repository includes focused missions for these interactions:
keyboardControls.mission.jssubmits login with Enter and dismisses a dialog with Escape.javascriptDialogs.mission.jscovers alert, confirm, prompt, and beforeunload responses.shipMapIframe.mission.jsfills, clicks, and validates content inside an iframe.
Run them from the examples repository:
npm run mission:keyboard
npx testronaut missions/shipMapIframe.mission.js
Reports and analyticsβ
Expanded report turns show the tool name and recorded arguments. Mission Control
also discovers tool names such as press_key for analytics filtering. Iframe
targeting is currently recorded as an argument to tools such as fill and
click; analytics and run comparisons do not yet expose iframe usage as a
separate category.