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.

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 both features:

• keyboardControls.mission.js submits login with Enter and dismisses a dialog with Escape.
• shipMapIframe.mission.js fills, 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.