Commands reference

The protocol has 46 commands. Every one below is derived from the handler that implements it, so the parameters are the parameters the Runtime actually reads.

Required means the Runtime refuses the call without it. A parameter marked optional may still be needed for the command to do anything useful - the handler simply does not reject its absence.

Send {"method": "<command>", "params": {...}}; see the protocol for framing and errors for what can come back instead.

Extended automation (4)

invoke_method

Call a Q_INVOKABLE method or slot

await client.invoke_method(path: str, method: str)

Parameter	Type	Required	Default
path	string	yes	-
method	string	yes	-

set_property

Write a property (triggers NOTIFY)

await client.set_property(path: str, property: str, value)

Parameter	Type	Required	Default
path	string	yes	-
property	string	yes	-
value	any	yes	-

wait_for_property

Block until a property reaches a value

await client.wait_for_property(path: str, property: str, value, *, timeout: int=5000, interval: int=100)

Parameter	Type	Required	Default
path	string	yes	-
property	string	yes	-
value	any	yes	-
timeout	int	no	5000
interval	int	no	100

wait_for_signal

Block until a signal fires once

await client.wait_for_signal(path: str, signal: str, *, timeout: int=5000)

Parameter	Type	Required	Default
path	string	yes	-
signal	string	yes	-
timeout	int	no	5000

Interaction (7)

drag

Drag source → target

await client.drag(path: str, from_x: int, from_y: int, to_x: int, to_y: int, *, button: str='left', modifiers: list[str] | None=None)

Parameter	Type	Required	Default
from_x	int	yes	-
from_y	int	yes	-
to_x	int	yes	-
to_y	int	yes	-
button	string	no	-
path	string	yes	-
modifiers	any	no	-

highlight_object

Overlay a coloured frame for debugging

await client.highlight_object(path: str, *, duration: int=2000, color: str='red')

Parameter	Type	Required	Default
path	string	yes	-
duration	int	no	2000
color	string	no	red

key_press

Press a single key (or chord like Ctrl+C)

await client.key_press(path: str, key: str, *, repeat: int=1)

Parameter	Type	Required	Default
key	string	yes	-
repeat	int	no	1
path	string	yes	-

mouse_click

Click at object centre (button, count configurable)

await client.mouse_click(path: str, *, button: str='left', click_type: str='single', x: int | None=None, y: int | None=None, modifiers: list[str] | None=None)

Parameter	Type	Required	Default
button	string	no	-
clickType	string	no	single
x	int	no	-
y	int	no	-
path	string	yes	-
modifiers	any	no	-

screenshot

PNG of a widget or whole window

await client.screenshot(path: str | None=None)

Parameter	Type	Required	Default
path	string	no	-

scroll

Wheel scroll on a widget

await client.scroll(path: str, *, dx: int=0, dy: int=0, modifiers: list[str] | None=None)

Parameter	Type	Required	Default
dx	int	no	0
dy	int	no	0
path	string	yes	-
modifiers	any	no	-

type_text

Type into a focusable widget

await client.type_text(path: str, text: str)

Parameter	Type	Required	Default
text	string	yes	-
path	string	yes	-

Mocking + multi-window (3)

clipboard

Read or write the system clipboard

await client.set_clipboard(text: str)
await client.get_clipboard()

Parameter	Type	Required	Default
text	string	no	-

emit_signal

Programmatically emit a signal (test stub)

await client.emit_signal(path: str, signal: str, args: list | None=None)

Parameter	Type	Required	Default
path	string	yes	-
signal	string	yes	-
args	array	no	-

list_windows

Enumerate all top-level windows - each entry carries windowType (window/dialog/popup/tooltip...) and embedded (from 0.6.0)

await client.list_windows()

Takes no parameters.

Model / view data (2)

get_model_data

Cell values by index + role

await client.get_model_data(path: str, *, row: int | None=None, column: int | None=None, start_row: int | None=None, end_row: int | None=None, columns: list[int] | None=None, role: str='display')

Parameter	Type	Required	Default
path	string	yes	-
role	string	no	-
row	int	no	-
column	int	no	-
start_row	int	no	0
end_row	int	no	totalRows - 1
columns	array	no	-

get_model_info

Row/column count + role names of a model

await client.get_model_info(path: str)

Parameter	Type	Required	Default
path	string	yes	-

Object discovery (10)

cancel_pick

Disarm picking (from 0.6.0)

Takes no parameters.

find_object

Resolve a single object by path, or search by name/class/properties within an optional root

await client.find_object(*, path: str | None=None, object_name: str | None=None, class_name: str | None=None, properties: dict | None=None, root: str | None=None, all_matches: bool=False)

Parameter	Type	Required	Default
path	string	no	-
objectName	string	no	-
className	string	no	-
root	string	no	-
properties	object	no	-
all	bool	no	-

get_children

Direct children of an object

await client.get_children(path: str, *, class_name: str | None=None)

Parameter	Type	Required	Default
path	string	yes	-
className	string	no	-

get_meta

What an object can do: class chain, signals, invokable methods, properties (from 0.6.0)

await client.get_meta(path: str)

Parameter	Type	Required	Default
path	string	yes	-

get_object_tree

Recursive subtree from a root

await client.get_object_tree(*, root: str | None=None, depth: int=-1)

Parameter	Type	Required	Default
root	string	no	-
depth	int	no	-1

get_parent

The parent of an object

await client.get_parent(path: str)

Parameter	Type	Required	Default
path	string	yes	-

get_properties

Read N properties of an object

await client.get_properties(path: str, properties: list[str] | None=None)

Parameter	Type	Required	Default
path	string	yes	-
properties	array	no	-

list_objects

Find objects by class_name / object_name

await client.list_objects(*, object_name: str | None=None, class_name: str | None=None, root: str | None=None, recursive: bool=True)

Parameter	Type	Required	Default
objectName	string	no	-
className	string	no	-
root	string	no	-
recursive	bool	no	-

object_at

Hit-test a point against the live tree - the Inspector picker (from 0.6.0)

await client.object_at(x: float, y: float, *, window: str | None=None)

Parameter	Type	Required	Default
x	number	yes	-
y	number	yes	-
window	string	no	-

pick_element

Arm native element picking - pushes element_hovered/element_picked (from 0.6.0)

Parameter	Type	Required	Default
highlight	bool	no	true

Performance (3)

frame_time

FPS + min/avg/max frame duration over a window

await client.frame_time(path: str | None=None, duration_ms: int=1000)

Parameter	Type	Required	Default
duration_ms	int	no	1000
path	string	no	-

memory_snapshot

Process RSS / VSize / threads / heap

await client.memory_snapshot()

Takes no parameters.

paint_count

Count paint events on a widget over a window

await client.paint_count(path: str, duration_ms: int=1000)

Parameter	Type	Required	Default
path	string	yes	-
duration_ms	int	no	1000

Protocol (4)

echo

Returns {"text": <input>} - diagnostic only

await client.echo(text: str)

Parameter	Type	Required	Default
text	string	yes	-

handshake

Negotiate protocol version + auth - mandatory first message

Parameter	Type	Required	Default
min_version	int	no	1
max_version	int	no	1
token	string	no	-

ping

Health check, returns {"pong": true}

await client.ping()

Takes no parameters.

version

Runtime version, protocol version, Qt version, and one status line per toolkit backend

await client.version()

Takes no parameters.

Push subscriptions (5)

list_subscriptions

List active subscriptions on this connection

await client.list_subscriptions()

Takes no parameters.

subscribe_destroyed

Push one object_destroyed when the QObject is destroyed

await client.subscribe_destroyed(path: str, callback=None)

Parameter	Type	Required	Default
path	string	yes	-

subscribe_property

Push property_changed events for a property

await client.subscribe_property(path: str, property: str, callback=None)

Parameter	Type	Required	Default
path	string	yes	-
property	string	yes	-

subscribe_signal

Push signal_emitted events for a signal

await client.subscribe_signal(path: str, signal: str, callback=None)

Parameter	Type	Required	Default
path	string	yes	-
signal	string	yes	-

unsubscribe

Cancel a subscription

await client.unsubscribe(subscription_id: str)

Parameter	Type	Required	Default
subscription_id	string	yes	-

Recording (2)

start_recording

Begin recording user interactions

await client.start_recording()

Takes no parameters.

stop_recording

End recording, return the script

await client.stop_recording()

Takes no parameters.

Touch & gestures (5)

multi_touch

Arbitrary multi-finger sequence

await client.multi_touch(path: str, touches: list[dict])

Parameter	Type	Required	Default
touches	any	yes	-
path	string	yes	-

pinch

Two-finger pinch with scale + optional rotation

await client.pinch(path: str, start_distance: int, end_distance: int, *, center_x: int | None=None, center_y: int | None=None, rotation: float=0.0, duration: int=300)

Parameter	Type	Required	Default
start_distance	int	yes	-
end_distance	int	yes	-
duration	int	no	300
steps	int	no	10
rotation	number	no	0.0
center_x	int	no	-
center_y	int	no	-
path	string	yes	-

swipe

Directional swipe

await client.swipe(path: str, from_x: int, from_y: int, to_x: int, to_y: int, *, duration: int=300, steps: int=10)

Parameter	Type	Required	Default
from_x	int	yes	-
from_y	int	yes	-
to_x	int	yes	-
to_y	int	yes	-
duration	int	no	300
steps	int	no	10
path	string	yes	-

touch_long_press

Long press with configurable duration

await client.touch_long_press(path: str, *, x: int | None=None, y: int | None=None, duration: int=800)

Parameter	Type	Required	Default
duration	int	no	800
x	int	no	-
y	int	no	-
path	string	yes	-

touch_tap

Single-finger tap

await client.touch_tap(path: str, *, x: int | None=None, y: int | None=None, duration: int=50)

Parameter	Type	Required	Default
duration	int	no	50
x	int	no	-
y	int	no	-
path	string	yes	-

Visual verification (1)

screenshot_compare

Diff a widget against a baseline PNG

await client.screenshot_compare(baseline: str, *, path: str | None=None, threshold: float=0.02)

Parameter	Type	Required	Default
baseline	string	yes	-
threshold	number	no	0.02
channel_tolerance	int	no	10
path	any	no	-