dusk:fill

Focus, clear, type, and settle a text field in a single call. dusk:fill promotes the manual focus + clear + type + settle + stale-retry dance into one first-class command, so an agent no longer re-discovers the sequence (and its frame-await + retry subtleties) on every form.

Internally dusk:fill composes the existing gated ext.dusk.focus, ext.dusk.clear, and ext.dusk.type handlers verbatim, so it inherits the full 6-step actionability gate, IME focus, onChanged / form-validator firing (via userUpdateTextEditingValue), and post-action snapshot semantics. It re-resolves the ref before each attempt and retries the whole sequence once if the ref goes stale mid-fill.

Synopsis
Arguments
Returns
Stale-retry
Examples
See also

Synopsis

dart run fluttersdk_dusk dusk:fill --ref= --text=
                                    [--includeSnapshot]
                                    [--[no-]checkStable]
                                    [--[no-]checkReceivesEvents]

dusk:fill requires a running Flutter session (CommandBoot.connected). It dials the VM Service URI, calls ext.dusk.fill, and prints either a one-line success (Filled ) or the full JSON envelope when --includeSnapshot is set.

Arguments

Option	Type	Default	Required	Description
`--ref`	string	(none)	yes (`mandatory: true`)	Text-field ref token (`e1` from a prior `dusk:snap`, or `q1` from a prior `dusk:find`). Empty values trigger a CLI-side error with exit code `1` before the VM Service call.
`--text`	string	(none)	yes (`mandatory: true`)	Value to set. Replaces existing content. Pass an empty string to clear the field.
`--includeSnapshot`	flag	`false`	no	Embed the post-fill snapshot YAML in the response.
`--checkStable`	flag	`true`	no	Run the Stable (2-frame rect-unchanged) actionability gate during the type step.
`--checkReceivesEvents`	flag	`true`	no	Run the Receives-Events (front-most hit-test) actionability gate during the type step.

Returns

Exit code	Meaning
`0`	Field filled. Emits `Filled` (default) or the full JSON envelope when `--includeSnapshot` is set.
`1`	`--ref` or `--text` was missing (CLI-side guard fires before the VM Service call).
non-zero	VM Service handler returned an error: ref not found, actionability gate failure, no editable under the ref, or a stale handle that did not recover on retry.

Success envelope (--includeSnapshot on):

{
  "ref": "e7",
  "text": "[email protected]",
  "filled": true,
  "snapshot": "[ref=e7] role=textbox typeable:true ..."
}

Stale-retry

dusk:fill re-resolves the ref via the registry before each attempt. When a q handle's stored predicates transiently miss (the field is rebuilding mid-fill), the resolver reports a stale handle; dusk:fill re-runs the whole resolve + focus + clear + type sequence once so the second pass walks the now-settled tree. A second stale outcome surfaces a typed stale error envelope so the agent re-snaps or re-finds rather than looping. Prefer a q handle (from dusk:find) for fields that may rebuild between snapshot and fill; the retry then re-resolves cleanly.

Examples

1. Fill an email field in one call

dart run fluttersdk_dusk dusk:snap > /tmp/snap.yaml
# locate the email field's eN in /tmp/snap.yaml
dart run fluttersdk_dusk dusk:fill --ref=e7 --text="[email protected]"

[ok]      Filled e7

2. Clear a field

dart run fluttersdk_dusk dusk:fill --ref=e7 --text=""

3. Fill a re-resolvable handle that survives rebuilds

dart run fluttersdk_dusk dusk:find --key="email-input"   # -> q1
dart run fluttersdk_dusk dusk:fill --ref=q1 --text="[email protected]" --includeSnapshot