Skip to main content

​
fill versus type

fill replaces. type appends. Reaching for type when you meant fill is how a field ends up containing hellohello, and neither call will complain.

​
press takes text, not key

Both are accepted today, and text wins when both are present. Use text. It is what the tool description documents.
This one has history worth knowing. The implementation used to read args.key and default to Enter, so the documented call, { action: "press", args: { text: "Escape" } }, silently sent Enter and reported success.Three consequences, worst last: the requested key never arrived, so Escape-to-close and Tab-traversal went unverified while looking verified; nothing in the result said the argument had been ignored; and Enter is not a neutral substitute. On a focused field inside a form it submits it. A request to close a dialog could file the form behind it.Two field reports were exactly this, both diagnosed as “synthetic events don’t reach the app”. Wrong root cause: the event reached the app perfectly well and simply said Enter.
That bug is fixed, and the reason it is written down here is that it is the exact shape of failure Reticle exists to catch. An action that reports success while doing something else.

​
Batching

Several actions in one round trip:
reticle_act_sequence returns ok: true when the steps were dispatched, not when they worked. Batch the setup, then prove the outcome with reticle_act_and_wait on the final step.

​
Real versus synthetic input

inputMode in the response says which you got. synthetic means events dispatched programmatically. Correct for the overwhelming majority of apps. real means native CDP input, available under reticle drive, and needed by a few drag-and-drop and pointer-gesture libraries.
On a throttled tab, synthetic timers and pointer gestures can silently no-op. Pass refuseWhenThrottled: true to fail loudly instead of acting into a tab the browser has paused.

​
What every action reports

valueChanged, focusMoved, domMutatedWithin, defaultPrevented, occluded and occludedBy. Plus the element’s testid, component and source file and line. occluded is the answer to a large share of “the button doesn’t work” reports: the click landed on the modal overlay sitting on top of it.

Full field-by-field walkthrough

What each effect field tells you, with a real response.
Last modified on August 14, 2026