Skip to main content

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:

ArgumentRequiredDescription
keyYesA Playwright key or shortcut such as Enter, Escape, Tab, Control+B, or Meta+B.
selectorNoA 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, or beforeunload (required)
  • action: accept or dismiss (required)
  • message for an exact match, or messageIncludes for a substring match
  • input only when accepting a prompt
  • timeoutMs from 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​

ToolUse it forImportant arguments
fillEntering text into an editable fieldselector, text, optional frame
clickActivating a control by selectorselector, optional frame
click_textActivating a control by its visible texttext
press_keyKeys and keyboard shortcutskey, optional selector
check_textConfirming visible texttext, optional searchAllFrames

Runnable examples​

The official examples repository includes focused missions for these interactions:

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.