Tools

The same tools are offered over MCP and through the CLI. This page is generated from the schemas the agent itself reports (tools/list), captured from version 0.1.0-SNAPSHOT. For the schema of the version you run, ask the running agent: java -jar <agent jar> tools <tool>.

describe_ui

Read-only.

The app facts the app plugin reports for the live client: activeTab, the navigate targets (navTargets: the friendly names, and navTargetEntryPointIds: the entry-point ids), the toolbar's toolbarActions (id/label/enabled/submenu), the menu bar's leaf menuPaths, navEntryPoints (roots, children), the open view's viewTabs and sections (every section it registered, including one never built - 'created':false; target it by its 'id') with sectionProblems, the plugins' domain steps as 'vocabulary' sentences (id, kind, sentence; the vocabulary tool has their params), and any waiting dialog ('dialog': title, message, buttons - answer it with the 'answer' verb). Tables, buttons and fields are read from the element tree with 'snapshot' or 'read'. Pass 'fields' to get only the parts you need.

Parameter	Type	Description
fields	array of string	Only these top-level fields, e.g. ["sections","dialog"] or ["activeTab","viewTabs"]; default all.

do_action

Acts on the app.

Execute ONE step against the live client and return pass/fail and its duration ('ms'). A step is a verb (click, type, press, ..., contextMenu) or one of the app steps navigate, close, loginAs. A successful step is recorded, unless it has no Java form (a loginAs after the first step, a target by ref): it runs but is not recorded, and 'notRecorded' says why. A do step is recorded even when its domain step has no Java form: export_recorded_test writes it, export_test refuses it. The 'action' object uses the step schema, e.g. {"action":"navigate","target":"home"} or {"action":"expect","target":{"role":"table"},"rows":{"op":"gte","value":1}}. A step that opens a message or confirmation returns at once with 'dialog' (title, message, buttons); navigate, close and loginAs refuse to run until it is answered with the 'answer' verb. A step may carry say: its sentence (one line, kept in the recording and the recorded test).

Parameter	Type	Description
action required	object	A step named by its 'action' field: a verb, navigate / close / loginAs, or do (a plugin's domain step: {"action":"do","step":<id>,"params":{<name>:<value as text>}}, which reports its filled sentence and the steps it ran, and is recorded as one step). The verbs are also tools of their own, with full argument schemas.
record	boolean	false keeps this step out of export_test's recording (used by tests)
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

do_actions

Acts on the app.

Execute SEVERAL steps in order against the live client, in one call, stopping at the first failure. Prefer this over repeated do_action when the next steps are already known. Returns {passed, ran, total, steps:[{passed, action, message}]}; successful steps are recorded for export_test exactly as do_action records them. Example: {"actions":[{"action":"navigate","target":"home"},{"action":"click","target":{"role":"tab","name":"Customer"}},{"action":"close"}]}. A step may carry say: its sentence.

Parameter	Type	Description
actions required	array of object	Steps to run in order
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

batch

Acts on the app.

Run SEVERAL steps in ONE call, in order, stopping at the first that does not pass - use it whenever the next steps are already known. Each step runs, answers and records exactly as its own tool call would, so export_test writes the same test either way; 'read' steps record nothing, and a 'read' that finds nothing stops the batch. Returns {passed, ran, total, ms, steps:[{verb, passed, message, ms, recorded?, notRecorded?, ...}], snapshot?, snapshotError?}. A snapshot that cannot be taken keeps the steps and reports {errorType, message, details} as snapshotError. A harness error (CAPABILITY_GAP, INPUT_ERROR) is a tool error naming the step; the steps before it ran and were recorded. Example: {"steps":[{"verb":"menu","path":["File","New order"]},{"verb":"type","target":{"role":"text","name":"Customer"},"text":"Ada"},{"verb":"press","keys":"Enter"},{"verb":"expect","target":{"role":"tab","name":"New order · Ada Shop Ltd"},"state":["selected"]}]}.

Parameter	Type	Description
steps required	array of object	The steps, in order. Each is {"verb": <name>, ...the arguments that verb's own tool takes}.
snapshot	any	true, or the snapshot tool's arguments (target, depth, compact, ...): a snapshot taken after the last step that ran, pass or fail.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

export_test

Acts on the app.

Write the steps recorded since the last session reset as a JUnit @UiTest class under <module>/src/test/java/<package>/<class>.java (the module is the app plugin's export module, else the working directory; dir or -Dswingui.testsDir overrides, and a working directory with no pom.xml or build.gradle makes the result carry a warning naming where the file went). The test starts where the recording did, right after a reset, so it must begin by getting to its own starting screen: without an app plugin a reset only closes dialogs, and startWarning flags a test that does not begin with menu, press or navigate. Only steps with a Java form are recorded (verbs, including expect for checks; navigate, close, a leading loginAs; do steps), except a do step whose domain step has no Java form: a recording with one is refused, naming it - export it with export_recorded_test instead. Refuses a recording that did not begin at a reset or a recording start, a bad class/method/package name, an existing file, or an empty recording, naming each problem; a refusal keeps the recording. A step and its checks are one block; sentences become comments.

Parameter	Type	Description
class required	string	Test class name; must end in UiIT, e.g. PlaceOrderUiIT
method	string	Test method name (default: recorded)
package	string	Java package (default: the app plugin's export package, else 'recorded')
dir	string	The test sources root to write under, e.g. <project>/src/test/java; wins over -Dswingui.testsDir and the plugin's module. A relative one is under the APP's working directory. Name it when the app runs outside the project
clear	boolean	Empty the recording after exporting (default: true); reset before recording the next test. Refused while a recording started by recording start or the person's Record runs: export with clear false, or stop it first
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

export_recorded_test

Acts on the app.

Write the steps recorded since the last session reset as a recorded test file <recorded tests folder>/<name>.json: UI steps and checks of what is visible, no compiling; run it with run_recorded_test, from the palette, or in Maven with the JUnit runner (RecordedTests). Same rules as export_test: it must have begun at a reset or a recording start, startWarning flags a recorded test that does not begin with menu, press or navigate, an empty recording or a bad name is refused, and an existing file is never overwritten - except the recorded test the recording came from (loaded in the palette, or exported before without clear). A folder that cannot be written is refused, naming it. A recorded test holds exact values: check data the test creates or data known to exist; a value the app makes up (a new order number, today's date) only when your start makes it predictable - otherwise check something else or write a Java test. Format version 2 (3 when it holds do steps, with requires naming their plugins): each step with its checks nested, sentences and groups kept.

Parameter	Type	Description
name required	string	The file name without .json, e.g. place-order
dir	string	The folder; default the recorded tests folder: agent option recorded=, else -Dswingui.recordedDir, else uitest in the app's working directory
description	string	What the recorded test does, one sentence
clear	boolean	Empty the recording after exporting (default: true); reset before recording the next recorded test. Refused while a recording started by recording start or the person's Record runs: export with clear false, or stop it first
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

run_recorded_test

Acts on the app.

Run a recorded test file on the live app and report it: one of 'name' (in the recorded tests folder), 'path', or 'test' (the file's JSON inline). It begins as every recorded test does, with a reset (dialogs closed; with an app plugin its reset), runs every step as do_action would WITHOUT recording, and stops at the first that fails; that step carries what its locators match now, a scoped tree and a picture of the window (written under 'evidence', default target/ui-screenshots/failures). Returns {passed, ran, total, steps, report}; ran and total count steps, each entry of steps is a step or a check: [{n, say?, action, passed, ms, message?, reason?, details?, warning?, diagnostics?}], n a step number (7) or a check label ("7.2"); action is the step's technical line. After a failure take a new snapshot before using refs. Refused (BUSY) while a person records, answers or replays in the palette. A file with do steps is checked before anything runs: a plugin its 'requires' names that is not ready is CAPABILITY_GAP, a step or param that plugin does not offer is BAD_INPUT naming the step and its line. From a shell the CLI exits 4 when the recorded test fails.

Parameter	Type	Description
name	string	A recorded test in the recorded tests folder, without .json, e.g. place-order
path	string	A recorded test file, absolute or relative to the app's working directory
test	object	The recorded test file's JSON inline (what export_recorded_test writes)
evidence	string	The folder for the failing step's picture; default target/ui-screenshots/failures
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

snapshot

Read-only.

The live client as an element tree: every showing window, dialog and popup (focused window first, popups last), each element with role, name, value, state and a ref (e1, e2, ...). Refs stay valid until the next snapshot; pass one as {"ref":"e12"} as a verb's target. SCOPE IT: an unscoped snapshot is the whole app and costs thousands of tokens. Give a 'target' locator (e.g. {"scope":["tab:Customer"],"role":"section","name":"Header"} or {"role":"tab","name":"Line items"}) for one element's subtree, 'depth' for a few levels, and compact:true to drop rows and items. The answer ends with 'size' {nodes, bytes, scoped}.

Parameter	Type	Description
window	string	Only the roots this names: main | popup | dialog | dialog:<title> | window:<title>
ref	string	Only this element's subtree (a ref from the previous snapshot)
target	object	Only this element's subtree, found like a verb's target - a tab's content for a tab. At most one of window, ref and target.
depth	integer	Levels of nodes to include below the windows (or the scoped element), which is level 1; deeper nodes are cut and their parent marked truncated. 2-4 is usually enough.
compact	boolean	Drop table/list/tree rows and items, scroll geometry and expanded paths (columns and rowCount stay); maxRows defaults to 0.
maxNodes	integer	Node budget, default 400; cut parts are marked truncated
maxRows	integer	Rows per table, list or tree, default 20

read

Read-only.

Reads one element without acting: its node, or with row/column one table cell or row. 'target' is required for every form except menuItems. A node carries 'tooltip' when the element (or the rendered cell) shows one. A target that does not resolve returns found:false with candidates.

Parameter	Type	Description
target	object	A UI element: {"ref":"e12"} from the last snapshot, or a locator. row/column/item/point address a part of it.
maxRows	integer	Rows for a table, list or tree
form	node · all · geometry · candidates · menuItems	What to read: node (default; {found,node}), all (every match; {found,nodes}), geometry ({found,geometry}), candidates ({candidates}) or menuItems ({found,items}; needs 'path', takes no target)
path	array of string	menuItems form: the menu path to list the items under

screenshot

Read-only.

A PNG of the app: the target element, or the current window when no target is given. It PAINTS the app's own components into an offscreen image - it never grabs the screen - so it captures the client whether or not it is in front, takes no focus, and cannot catch another application's window. Give a 'target' for one dialog, panel, table or toolbar, and 'region' for a snippet inside it. Anything drawn in a window of its own (an open popup menu, a combo dropdown, a tooltip) is NOT in the image - capture that window instead. The person's palette and any boxes shown in the app are not in the image. 'palette': true keeps the palette, the boxes and the open menus in the picture, as the person sees the window (for documentation); default false. A read: nothing is recorded; to capture screens in a recorded test, use the 'screenshot' step in a batch, which writes a file. Use it for an aesthetic call - alignment, cropping, overlap, proportion - and an 'expect' for anything that is really a number or a boolean.

Parameter	Type	Description
target	object	A UI element: {"ref":"e12"} from the last snapshot, or a locator. row/column/item/point address a part of it.
window	string	A whole window instead of the current one: main | dialog | dialog:<title> | window:<title> (a title ending in * matches a prefix). Ignored when 'target' is given.
region	object	A snippet of the target instead of all of it: x, y, w, h as fractions 0..1 of its bounds (the way 'point' works).
maxSize	integer	Longest side of the returned image, default 1200 times 'scale'; it is scaled down to fit.
scale	number	Image pixels per screen pixel, 1 to 4, default 1: 2 paints the app as a 2x (HiDPI) display would, same layout, finer text and lines - for images people will look at.
palette	boolean	true keeps the person's palette and open menus in the picture (for documentation); default false.

inspect

Acts on the app.

Work WITH the person at the app, only when the palette is on (the default; off with palette=off, mode=background or headless); otherwise a CAPABILITY_GAP. highlight: box every match of 'target' (numbered when several) with 'question' on a bar; they click the check mark on the one they mean (outcome confirmed, chosen n, its locator) or 'None of these' (rejected). pick: they click the element they mean - the click does not reach the app - and you get its locator. hover: a box follows their pointer and names what is under it as they see it (not the locator). clear: removes your boxes and question. The recording itself: the recording tool. While a person records, picks, answers or replays, no test run can take the lease.

Parameter	Type	Description
op required	highlight · pick · hover · clear
target	object	A UI element: {"ref":"e12"} from the last snapshot, or a locator. row/column/item/point address a part of it.
question	string	highlight, pick: the question on the bar in the app window.
wait	integer	Milliseconds to wait for the person: highlight and pick default 60000, at most 300000 (highlight with 0 only shows the boxes).
on	boolean	hover: true starts it, false stops it.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

recording

Acts on the app.

The recording the agent and the person at the app make together (works with the palette on or off). start {reset?}: a fresh recording; with the palette on the person's steps join it and the palette shows it; reset:true resets the app first, as a test starts. stop: ends it (the person's Done does too); after it no step joins. Steps are numbered 1..n; a step is an action and the checks after it, numbered n.k (7.2); checks before any action are step 1. list {wait?}: state, who started it, rev, and every step with n, author (person, agent, loaded), line, java, its step JSON, say, edited (changed and not replayed since), group (its number in groups) and its checks nested under it ({n: "7.1", ...}), plus groups [{from, to, say}] in step numbers; a check-only step 1 has no line, step or java; wait (ms) waits until it stops (not for a session reset's). insert {at, step}: an action at a step number (before the step now there) or a check at a label ("7.2"), NOT run (marked edited until a replay passes it); nothing can go in front of a check-only step 1. delete {n | from, to}: a step goes with its checks, "7.2" only that check. move {n, to}: a step with its checks (a check is deleted and inserted again). edit {n, target | text | step | say}: n is a step or a check; say sets its sentence (one line, "" removes it) and may come with target, text or step. group {from, to, say}: steps from..to (two or more, whole steps, groups do not nest or overlap) under one sentence; the same range renames it. ungroup {n}: ends the group that holds step n, its steps stay. row {n, by}: a step or check on a table row names it by value (the key column's text: it still finds the row after a sort or a new row) or by position (its index); list shows each one's row {by, value, index}; the other way is known once the step ran (a loaded step: after one passing replay); an edit like the others. undo: takes back the last edit, by you or the person (a fold too). With a plugin vocabulary, raw steps fold as they are recorded: a run of one author's steps that is a domain step's pattern becomes one do step (step JSON {action: do, step, params, say}); list shows folded (how many raw steps) and raw (their lines), keepRaw, and where a run did not fold foldCandidates (a tie), foldSuggested (a step that only suggests) or foldUndecided (why). Checks, do steps, an author change, groups, steps with their own sentence, kept raw steps and a replay's start stop a fold. fold {from, to, step?}: folds those steps into the domain step whose pattern they match (step names it when more fit). unfold {n}: puts a fold's raw steps back, kept raw. keepRaw {from, to}: those steps never fold. Numbers close up after a delete; deleting or moving a step takes its checks along; pass rev from your last list so an edit is refused if the person changed the recording meanwhile. Every edit returns the new list. While one runs, session reset and test runs are refused; stop it first. replay {from?, to?, speed?}: runs the steps (with their checks) again without recording them and returns {passed, ran, total, reset, steps}: ran and total count steps, with one {n, action, passed, ms, message?} entry per step or check run (n as in list; action is its technical line); from step 1 it resets the app first, as the exported test starts. redo {from}: cuts step from and the ones after it, replays the steps before it from a reset, and records on (from = the number after the last step continues a stopped recording). export {as: recorded|java, ...}: as export_recorded_test / export_test, but keeps the recording. load {name | path}: a recorded test file becomes the recording (stopped; redo or insert to add to it).

Parameter	Type	Description
op required	start · stop · list · insert · delete · move · edit · group · ungroup · row · undo · fold · unfold · keepRaw · replay · redo · export · load
at	integer,string	insert: where it goes. An action: the step number it gets (1 to steps+1), before the step now there. A check: the label it gets, a step number and its place under it ("7.2"; k up to the step's checks + 1), or 1 for a check-only step 1. A step number (7) or a check label ("7.2").
n	integer,string	delete, move, edit, ungroup, row, unfold: a step number (7) or a check label ("7.2"). delete 7 deletes the step and its checks, delete "7.2" only that check; move takes a step (with its checks); edit "7.2" edits that check; ungroup takes any step of the group; unfold takes a folded step.
from	integer	delete, group, fold, keepRaw: first step of a range; replay: first step (default 1); redo: the step to record again (steps+1 continues).
speed	fast · normal · slow	replay: pauses for a person watching.
as	recorded · java	export: the format (required).
class	string	export java: the test class name.
method	string	export java: the test method (default recorded).
package	string	export java: the package.
name	string	export recorded: the file name without .json; load: a recorded test in the recorded tests folder.
dir	string	export recorded: the folder; export java: the test sources root (e.g. <project>/src/test/java).
description	string	export recorded: what the recorded test does.
clear	boolean	export: empty the recording afterwards (default false); refused while a recording started by start or the person's Record runs.
path	string	load: a recorded test file.
to	integer	delete, group, fold, keepRaw: last step of a range; move: the step number it has afterwards; replay: last step (default: the last).
say	string	edit: the step's or check's sentence, one line of at most 200 characters ("" removes it), alone or with target, text or step; group: the group's sentence.
by	value · position	row: how the table row of step or check n is named: value (its key column's text, as recorded when a column told the rows apart) or position (its index).
step	object,string	insert, edit: a step or check as do_action takes it (an object); fold: the id of the domain step to fold into, when more than one fits (a string, from vocabulary list).
target	object	A UI element: {"ref":"e12"} from the last snapshot, or a locator. row/column/item/point address a part of it.
text	string	edit: the new text of a type, expect, setClipboard or drop step or check.
rev	integer	insert, delete, move, edit, group, ungroup, row, undo, fold, unfold, keepRaw, redo: the rev of your last list; refused if the recording changed since.
reset	boolean	start: reset the app first, as a test starts (default false).
wait	integer	list: milliseconds to wait until the recording stops (default 0: just read), at most 540000; a session reset's recording, which only you stop, is not waited for.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

vocabulary

Read-only.

The domain steps the ready plugins offer: one step that stands for the clicks and checks it takes, e.g. "Add {product} to the cart". list: every step with id, kind (act or check), sentence, about, params {name, type, optional, default}, plugin and folds (a one-line summary of the patterns a recording must match to fold into it, or why it has none), plus problems for steps a plugin offered that were dropped. describe {step}: one step in full: its params with choices (the values that fit in the app right now, e.g. product names; they help you pick, a call may pass others), its patterns, its body as steps with {param} placeholders, and its Java call. match {from, to}: a dry run of what steps from..to of the recording would fold into, each raw step looked at as if just recorded (the recording is not changed): folds [{from, to, step, params, say}] and notes [{from, to, kind: tie|suggested|undecided, steps, why?}], outOfTime:true when the matching ran out of time first; with no pattern to match, a hint instead. Call one with do_action {"action":{"action":"do","step":<id>,"params":{...}}} (a batch step: {"verb":"do","step":<id>,"params":{...}}). Without a plugin that offers a vocabulary, list is empty with a hint.

Parameter	Type	Description
op required	list · describe · match
step	string	describe: a step id from list (<plugin>:<id> when two plugins use the same id).
from	integer	match: the first step of the recording range.
to	integer	match: the last step of the recording range.

read_clipboard

Read-only.

The system clipboard's text as {text}, e.g. to check what a copy in the app left there (a tab between cells, a line break between rows). text is null when the clipboard holds no text. A read: nothing is recorded; a test reads it with ui.clipboardText().

No parameters.

read_file_chooser

Read-only.

The showing file chooser as {found, folder, name, nameFocused, lookAndFeel}: the absolute path of the folder it shows, the file-name field's text, whether that field has focus (so a press with no target lands in it), and the look and feel whose key bindings it runs. One look; it waits the driver's default unless 'timeout' (ms, 0 = no wait) is given; found is false with the reason when no chooser shows. A read: nothing is recorded; a test reads it with ui.fileChooser().

Parameter	Type	Description
timeout	integer	Milliseconds to wait for a chooser to show; 0 looks once. Omitted: the driver's default wait.

click

Acts on the app.

Clicks an element as a mouse would: the click is posted into the client's event queue at the element (or its row/column/item/point), where AWT decides who receives it. A disabled, hidden, covered or modal-blocked target is refused. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
target required	object	The element to click.
button	left · right	Mouse button; default left.
count	integer	1, 2 or 3 clicks; default 1.
modifiers	array of string	Keys held while clicking: Mod (Cmd on macOS, Ctrl elsewhere), Shift, Ctrl, Alt, Meta. Mod toggles a row into the selection; Shift extends it.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

type

Acts on the app.

Types text into a field or a table cell as a keyboard would. A cell target (row and column) is clicked, then edited; commit presses Enter after typing. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
target required	object	The field, or a table with row and column.
text required	string	The text to type.
replace	boolean	Replace what is there (select all first); default true.
commit	boolean	Press Enter after typing; default false.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

press

Acts on the app.

Presses a key chord, e.g. "Enter", "Escape", "Mod+O", "Shift+Tab". With a target, focuses it first; without one the keys go to the showing modal dialog, else the focused window. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
keys required	string	The key chord.
target	object	The element to focus first.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

check

Acts on the app.

Sets a check box, toggle or Boolean table cell to the given state by clicking it; does nothing when it is already in that state. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
target required	object	The check box, or a table with row and column of a Boolean cell.
checked required	boolean	The wanted state.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

select

Acts on the app.

Selects by clicking: a combo box item (opens its popup, clicks the item), list items (the first plain, the rest with Mod), or a tab of a tab strip. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
target required	object	The combo box, list or tab strip.
item	string	The item's text as shown.
items	array of string	Several list items, as shown.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

pick

Acts on the app.

Clicks down a path of items in the showing popup (a dropdown button's menu, a context menu), opening submenus on the way. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
path required	array of string	Item labels from the popup down; a submenu's label comes before its items.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

menu

Acts on the app.

Invokes a main-window menu-bar item by its label path. An in-window menu bar is clicked; the native macOS screen menu bar has no input path, so its item is invoked directly (recorded as via:api). Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
path required	array of string	Menu, submenus and item, e.g. ["File", "Export", "PDF"].
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

context_menu

Acts on the app.

Right-clicks an element (with row/column/item/point) and clicks down 'path' in the context menu that opens. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
path required	array of string	Labels from the context menu down to the item.
target required	object	The element to right-click.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

answer

Acts on the app.

Answers the showing modal dialog: clicks the button with this label, or with "escape" presses Escape and requires the dialog to close. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
button required	string	The button's label as shown ("Yes", "OK", "Assign"), or "escape".
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

choose_file

Acts on the app.

Answers the showing file chooser: types the path and presses Enter (falling back to the chooser's own approve, recorded as via:api), or with approve:false presses Escape. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
path	string	The file to choose; required unless approve is false.
approve	boolean	Approve (default true) or cancel.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

drag

Acts on the app.

Posts a mouse drag gesture from one element to another in the same window. A native drag is never started; use drop to deliver data. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
from required	object	Where the drag starts.
to required	object	Where it ends.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

drop

Acts on the app.

Drops files or text onto an element's drop target without the OS (recorded as via:api). Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
target required	object	The element to drop onto.
files	array of string	Absolute paths of existing files.
text	string	Text to drop instead of files.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

expect

Acts on the app.

Checks an element without acting, retrying until it holds or the timeout (default 10000 ms) passes. Give exactly one of state, text, value, tooltip, rows, cell, selected, shown, absent. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
target required	object	The element to check.
state	array of string	States that must hold; "!x" must not. The tokens: disabled, focused, selected, checked, readonly, editable, rollover, editing (a table with an open cell editor), atTop and atBottom (a scrollable element's viewport), expanded and leaf (a tree row), and any state the app reports for a section (e.g. hidden, incomplete). On a table target with a 'row' and no 'column' this is that ROW's selection (and focused); on a tree target with an 'item' it is that ROW's selected, expanded, leaf.
text	string	The element's text as shown (a cell with row and column).
value	string	A field's or combo's value, a toggle's true/false.
tooltip	string	The tooltip shown on hover, HTML stripped (a cell's with row and column); "" for none.
rows	object	Row count of a table, list, tree or combo: {op: eq|gt|gte|lt|lte, value}.
cell	object	One table cell: {row, column, expected}.
selected	array of integer	The rows of a table, list or tree that must be selected, and only those, e.g. [0, 1]; order does not matter. Use [] for nothing selected.
shown	boolean	true: the element is there and shown (not hidden); the same as state ["!hidden"] and the Java isVisible().
absent	boolean	true: the element is not there, e.g. a closed tab or dialog; waits until it is gone. Needs a locator, not a ref.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

scroll

Acts on the app.

Scrolls a table, tree, list or panel: to an end with 'to', by whole screens with 'pages', or until a row is in view by giving the target a 'row'. Exactly one of the three. It moves the viewport directly rather than posting wheel input, so it is exact and it fires the same change a scroll bar does - which is what continuous paging listens for. Read where it ended up from the element's 'scroll' block (x, y, width, height, maxX, maxY) or its atTop/atBottom states. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
target required	object	The scrollable element; add a 'row' to it to scroll that row into view.
to	top · bottom · left · right	Scroll all the way to this end.
pages	integer	Scroll by this many screens; negative scrolls back up.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

set_clipboard

Acts on the app.

Puts text on the system clipboard, as a copy in another application would - e.g. a block copied from Excel: a tab between cells, a line break between rows, each value as displayed. Paste it into the app with press "Mod+V" on the focused element (click the anchor cell first). It REPLACES what the user had on the clipboard. Read it back with read_clipboard. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
text required	string	The text. For a spreadsheet block: \t between cells, \n between rows.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

hover

Acts on the app.

Moves the pointer onto an element (inside true, the default) or off it again, so parts that show only on hover, such as a row's inline buttons, show or hide. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
target required	object	The element to hover.
inside	boolean	false moves the pointer off the element.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

resize_column

Acts on the app.

Drags a table column's right header edge by delta pixels (negative narrows it). Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
target required	object	A table target with a column and no row.
delta required	integer	Pixels to widen (positive) or narrow (negative).
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

resize_window

Acts on the app.

Resizes a window to width x height pixels. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
window required	string	The window: main, dialog, popup, dialog:<title> or window:<title>.
width required	integer	New width in pixels.
height required	integer	New height in pixels.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

close_window

Acts on the app.

Closes a window the way its title-bar close button would. Returns {passed, reason?, message, ms, recorded, pending?, realInput?, activations?, snapshot?}; the recorded step is what export_test writes (a ref becomes a locator; via:api marks a direct Swing call, fragile:true a target that needed nth or is a point).

Parameter	Type	Description
window required	string	The window: main, dialog, popup, dialog:<title> or window:<title>.
timeout	integer	Milliseconds this step may wait for its target to become actionable and for the app to settle.
snapshot	boolean	Also return a snapshot taken after the step.
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

plugin_call

Acts on the app.

Calls one method of a plugin's hooks by name. args is a JSON array, converted to the method's parameter types. Returns {"value": …}. Without 'plugin', the only plugin.

Parameter	Type	Description
plugin	string
method required	string
args	array of any
_lease	string	lease token from session op 'lease'; omit while nobody holds the lease

session

Read-only.

The agent itself. info (default): versions, app start, lease, plugins (the plugins array lists every plugin with its state). lease {owner, ttlMs}: take the agent for one owner; pass the token as _lease on every mutating call. release {token}. renew {token}: keep the lease alive while the test makes no call; answers renewed: false once the lease is gone. reset {alias | user+password}: the start of every test: close modal dialogs; with an app plugin also its reset (tabs, login as alias or user). Starts a fresh recording for export_test; refused while a recording runs (recording start or ● Record): recording stop or Done ends it. login {alias | user+password | relogin:true}: switch users mid-test. edt: the client's event-thread stack.

Parameter	Type	Description
op	info · lease · release · renew · reset · login · edt
owner	string
ttlMs	integer
token	string
alias	string
user	string
password	string
relogin	boolean
_lease	string