# Fluttersdk Dusk > fluttersdk_dusk: E2E driver for Flutter apps that lets an LLM agent see (snap, observe, screenshot) and act (tap, type, drag, scroll, navigate) on a running Flutter app via 33 MCP tools (`dusk_*`) and 34 matching CLI commands (`./bin/fsa dusk:*`). Snapshots emit a YAML Semantics tree with stable `[ref=eN]` tokens; `dusk_find` and `dusk_observe` mint re-resolvable `q` query handles. Every gesture passes a 6-step actionability gate with substring-parseable failure reasons (`not enabled`, `zero rect`, `off-viewport`, `not stable`, `obscured by`, `defunct`). TRIGGER when: any `dusk_*` MCP tool call, any `dusk:*` CLI command, `./bin/fsa` invocation, the user asks the agent to drive / inspect / test / debug a running Flutter app, the user mentions snap / observe / actionability / ref / eN / qN, or the conversation touches end-to-end testing of a Flutter UI. DO NOT TRIGGER when: only authoring `flutter_test` widget tests, only reading telescope ring buffers without driving the UI (use fluttersdk-telescope), or on - Skill: `fluttersdk/fluttersdk-dusk` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add fluttersdk/fluttersdk-dusk` - Raw SKILL.md: https://api.skillmd.com/api/skills/fluttersdk/fluttersdk-dusk/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: fluttersdk (https://skillmd.com/u/fluttersdk) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/fluttersdk/fluttersdk-dusk --- # fluttersdk_dusk End-to-end driver for Flutter apps, designed for LLM agents. The running app exposes a `ext.dusk.*` VM Service surface plus an MCP server; the agent calls `dusk_*` tools (or `./bin/fsa dusk:*` from a shell) to snap the Semantics tree, mint ref tokens, gesture against them, wait for conditions, screenshot, and hot-reload, all without a test file or rebuild between actions. This skill assumes the app already has dusk installed (a `kDebugMode`-gated `DuskPlugin.install()` in `lib/main.dart`, the MCP server in `.mcp.json`). If not, run `dart run fluttersdk_dusk dusk:install` once from the app root and verify with `./bin/fsa dusk:doctor`. ## 1. Core Laws 1. **Two ref token spaces.** `e` (snapshot-frozen, minted by `dusk_snap`) are deduped by `SemanticsNode.id`: the same widget across consecutive snaps returns the same `e` and the ref stays valid as long as the node remains mounted. They become defunct when the node unmounts (navigation, conditional render, list rebuild). `q` (re-resolvable, minted by `dusk_find` / `dusk_observe`) store a predicate and re-walk the live tree on every action. Use `e` right after the snap that minted them when the UI is static. Reach for `q` whenever the action might retry, the UI animates, or the agent holds the ref across a navigation. Never mix the spaces (no `e` from find, no `q` from snap). 2. **The 6-step actionability gate is mandatory.** Every `tap`, `hover`, `drag`, `dblclick`, `right_click`, `triple_click`, and `type` is gate-checked in this order: (0) defunct, (1) enabled, (2) zero-rect, (3) off-viewport (auto-scrolls when a `Scrollable` ancestor exists, then re-checks), (4) stable (2-frame rect drift, 0.5px threshold), (5) receives-events (hit-test path includes the target). Steps 4 and 5 accept `checkStable: false` / `checkReceivesEvents: false` overrides for flaky animations or known overlays. `scroll`, `select_option`, and `press_key` skip the gate by design. 3. **Failure reasons are substring contracts.** On gate failure the response carries one of these exact substrings; branch on the substring, not the full message: | Substring | Meaning | Agent's next move | |---|---|---| | `defunct (element no longer mounted)` | Element unmounted between snap and action | Re-snap, re-pick the ref | | `not enabled` | Widget's `isEnabled` semantics flag is false | Inspect upstream state; do not retry without changing it | | `zero rect` | Width or height is 0 | Wait for layout via `dusk_wait_for`; widget likely still building | | `off-viewport (rect=..., viewport=...)` | Auto-scroll did not bring it into view | Call `dusk_scroll` explicitly toward the rect, then retry | | `not stable (rect changed by Xpx)` | Mid-animation | Wait for animation to settle; pass `checkStable: false` only if animation is intentional | | `obscured by other widget (top=)` | Hit-test resolved a covering widget | Dismiss the overlay (often a modal: call `dusk_dismiss_modals`), or pass `checkReceivesEvents: false` | Stale `q` handles raise `Query handle ref=qN is stale: no live match for stored predicates`. Recover by calling `dusk_find` or `dusk_observe` again, not by retrying the same handle. 4. **Three tools run on the substrate, not in-isolate.** `dusk_hot_reload_and_snap`, `dusk_resize_viewport`, `dusk_device_profile`. The first runs CLI-side because an in-isolate handler cannot reload its own isolate. The viewport / device tools drive Chrome DevTools Protocol from outside the Flutter VM, so they only work on web with Chrome launched at a debug port (`artisan start --cdp-port=9222`). They will return `CDP not enabled` on mobile, desktop, or any web run without the flag. 5. **Network-idle and telescope readers need an adapter.** `dusk_wait_for_network_idle`, `dusk_console`, `dusk_exceptions` read through `fluttersdk_telescope`. Without `MagicTelescopeIntegration. install()` (or a custom adapter), pending-HTTP count is constantly 0 (network-idle returns immediately, `matched: true`) and the log / exception lists are empty. Treat them as wired before relying on them; check with one `dusk_console` call. 6. **CLI and MCP reach the same handler with the same parameters.** `dusk_tap { ref: "e7" }` and `./bin/fsa dusk:tap --ref=e7` invoke the same code path. Use MCP when the agent is wired through an MCP client; use the CLI from Bash when chaining shell logic or capturing output to a file. Two practical differences worth knowing: (a) MCP responses are always JSON. The CLI splits by verb: read / query verbs return JSON (`dusk:snap`, `dusk:observe`, `dusk:find`, `dusk:get_routes`, `dusk:console`, `dusk:exceptions`, `dusk:wait`, `dusk:wait_for_network_idle`, `dusk:hot_reload_and_snap`), and so does `dusk:reset_overlays`, which acts on the app but still prints its `{popped, escaped, dismissTapped}` object so you can see which layer cleared the screen; the 19 side-effect verbs (`dusk:tap`, `dusk:hover`, `dusk:drag`, `dusk:type`, `dusk:fill`, `dusk:clear`, `dusk:press_key`, `dusk:scroll`, `dusk:focus`, `dusk:blur`, `dusk:dblclick`, `dusk:right_click`, `dusk:triple_click`, `dusk:set_checkbox`, `dusk:select_option`, `dusk:navigate`, `dusk:navigate_back`, `dusk:modal`, `dusk:close_app`) print a one-line success summary by default and only emit JSON when `--includeSnapshot` is passed. `dusk:screenshot` writes bytes to disk and prints `Wrote N bytes...`; `dusk:install` / `dusk:doctor` print categorised reports. Pipe through `jq` only on the JSON-returning shapes. (b) `dusk_evaluate` is MCP-only (no CLI mirror); the dusk-aware Dart REPL lives behind `./bin/fsa tinker` (one-shot form: `./bin/fsa tinker --eval=""`). ## 2. Tool surface (33 MCP tools, 34 CLI commands) | Family | Tools | Mental model | |---|---|---| | See | `dusk_snap`, `dusk_observe`, `dusk_screenshot` | Snap returns the YAML tree with `e` tokens. Observe returns a structured candidate list with `q` handles plus enricher fields. Screenshot returns base64 PNG or JPEG (default JPEG q70). | | Find | `dusk_find` | Mints a `q` from `text` / `contains` / `semanticsLabel` / `key`. Re-walks on every action. | | Click family | `dusk_tap`, `dusk_dblclick`, `dusk_right_click`, `dusk_triple_click`, `dusk_hover`, `dusk_drag` | Pointer gestures, all gate-checked. `dusk_drag` takes `startRef` + `endRef`. | | Text input | `dusk_fill`, `dusk_type`, `dusk_clear`, `dusk_press_key`, `dusk_focus`, `dusk_blur` | `fill` is the default: focus + clear + type + settle in one call, with a stale-ref retry. `type` calls `userUpdateTextEditingValue` (fires `onChanged`, the Wind / Magic forms path). `press_key` synthesizes a `HardwareKeyboard` Down+Up; supports Enter, Tab, Escape, Backspace, Delete, Space, Arrow keys, Home, End, PageUp, PageDown, F1-F12. | | Form controls | `dusk_set_checkbox`, `dusk_select_option` | Idempotent: `set_checkbox` does nothing if already in the target state. `select_option` dispatches through `onChanged` directly, no popup walk. | | Scroll | `dusk_scroll` | Scrolls by `dx` / `dy` logical pixels, or `intoView: true` to bring a ref into view. Operates on the nearest scrollable ancestor. | | Wait | `dusk_wait_for`, `dusk_wait_for_network_idle` | `wait_for` polls every 200ms for `text` / `textGone` / `expression`, default 5s timeout. `wait_for_network_idle` waits for `idleMs` (default 500) of zero pending HTTP, max `timeoutMs` (default 5000). | | Navigation | `dusk_navigate`, `dusk_navigate_back`, `dusk_get_routes`, `dusk_dismiss_modals`, `dusk_reset_overlays` | `navigate` tries `Navigator.pushNamed`, then a consumer-registered `DuskNavigateAdapter`, then `SystemNavigator.routeInformationUpdated`. Returns `{ navigated, route, reason? }`. `dismiss_modals` pops `PopupRoute`s only; `reset_overlays` escalates through pop, Escape, and a Cancel-tap, and is idempotent. | | Diagnostics | `dusk_console`, `dusk_exceptions` | Telescope ring-buffer reads. Empty when telescope is not wired. | | Evaluation | `dusk_evaluate` (MCP-only) | Evaluates a Dart expression in the running isolate via the VM Service. Single expression, no semicolons. | | App control | `dusk_close_app` | `SystemNavigator.pop()`. Graceful; web `window.close()` may no-op if the tab was not script-opened. | | Composite | `dusk_hot_reload_and_snap` | Hot reload, then snap, screenshot, and recent exceptions in one round-trip. Returns `{ reloaded, durationMs, snapshot, screenshot, recentExceptions }`, or `{ reloaded: false, error, recentExceptions }` on compile failure. | | CDP (web-only) | `dusk_resize_viewport`, `dusk_device_profile` | Drive Chrome via CDP. 8 device presets: `iphone-x`, `iphone-13`, `iphone-15-pro`, `pixel-5`, `pixel-8`, `ipad-pro-12.9`, `desktop-1440`, `desktop-1920`. | Full per-tool input schema, return shape, and example calls: `${CLAUDE_SKILL_DIR}/references/mcp-tools.md`. CLI flags and exit codes: `${CLAUDE_SKILL_DIR}/references/cli-commands.md`. ## 3. The three agent loops ### A. Snap, act, verify (default for deterministic flows) ``` 1. dusk_snap Mint e tokens. Read the YAML. 2. Local reasoning, no tool call. 3. dusk_tap { ref: "e7" } Gate fires, gesture dispatches, response carries a post-action snapshot by default. 4. dusk_wait_for { text: "Saved" } Block on the expected post-condition. 5. dusk_snap Re-snap and confirm. ``` The post-action snapshot in step 3 is usually enough to skip step 5 on simple cases. Skip `dusk_wait_for` only when the action is synchronous (local state toggle); always wait when the action triggers HTTP, animation, or navigation. ### B. Observe once, act many (form fill, dynamic UI) ``` 1. dusk_observe { intent: "login form", roles: "textbox,button" } Returns candidates with q handles, role, label, bounds, magicFormField enricher when present. 2. dusk_type { ref: "q3", text: "user@example.com" } // q3 = Email 3. dusk_type { ref: "q4", text: "hunter2" } // q4 = Password 4. dusk_tap { ref: "q5" } // q5 = Submit 5. dusk_wait_for_network_idle { idleMs: 800 } 6. dusk_snap ``` `q` handles survive between candidates and small UI mutations. They throw `DuskStaleHandleException` when the predicate stops matching; recover by calling `dusk_observe` or `dusk_find` again. ### C. Hot reload then snap (after a code edit) ``` 1. 2. dusk_hot_reload_and_snap { screenshot: true } On success: { reloaded: true, durationMs: 740, snapshot, screenshot, recentExceptions: [] } On compile fail: { reloaded: false, error: "", recentExceptions: [] } 3. ``` Re-running this tool after a fix loops the agent through edit → reload → verify without leaving the conversation. Always inspect `recentExceptions` even on `reloaded: true`: a successful reload can still throw at runtime (e.g. a build-time null assertion firing on rebuild). ## 4. Picking between `e` and `q` | Use `e` when | Use `q` when | |---|---| | The UI is static; nothing animates between snap and action | The UI animates, scrolls, or rebuilds between snap and action | | The action runs immediately after the snap that minted the ref | The agent holds the ref across navigation, hot-reload, or wait | | The ref points at a static label (a header, a fixed icon) | The action might retry (gate failure, transient state) | | Performance matters and the ref is one-shot | The agent loops over many actions against the same logical widget | Default: snap returns `e`; use them inline. Switch to `dusk_find` / `dusk_observe` and `q` the moment the agent enters a retry or multi-step flow against the same target. **e-ref staleness on rebuild-prone pages.** `e` tokens are frozen to the Semantics node at snap time. The `RefRegistry` backing them does NOT re-resolve; on pages that rebuild (Settings, lists driven by async data, any page with conditional sections), use `dusk_find` from the start instead of snapping and then regretting the stale `defunct` failure. **`--semanticsLabel` over-match.** `dusk_find { semanticsLabel: "X" }` exact-matches against the accessibility label and resolves to the FIRST node; ambiguity is now surfaced via `matchCount` and `diagnostic` in the response. On forms with repeated labels ("Password" and "Confirm Password" both labelled "Password"), the handle points at the first match. Check the `matchCount` field in the response; when `> 1`, read the `diagnostic` key and add a second predicate (`--key`, `--text`, or `--contains`) before acting. Full disambiguation table: `references/actionability-and-refs.md` section "semanticsLabel exact-match and over-match". ## 5. Quick install + doctor (when dusk is missing) If `./bin/fsa dusk:snap` returns "VM Service URI absent" (or any connected command fails to attach), the app is not running or dusk is not installed. Separately, `dusk:resize` / `dusk:device` (web-only CDP tools) return "CDP not enabled" when Chrome was launched without a debug port. The agent should: ```bash # From the Flutter app root: dart run fluttersdk_dusk dusk:install # patches main.dart, scaffolds ./bin/fsa dart run fluttersdk_dusk mcp:install # writes .mcp.json ./bin/fsa start --device=chrome # or macos / linux / windows / ./bin/fsa dusk:doctor # 5 checks; only semanticsEnabled is hard fail ./bin/fsa dusk:snap # confirm the agent can reach the app ``` Magic-stack apps also get `MagicDuskIntegration.install()` injected after `Magic.init()` automatically; this wires the form / route / auth / gate / recent-HTTP enrichers that appear inside snapshot and observe payloads as `magicFormField: email`, `magicRoute: /login`, `magicGateResult: monitors.create.allowed`, etc. ## 6. References (load on trigger) | Read when... | File | |--------------|------| | Calling any `dusk_*` MCP tool: per-tool input schema, return shape, error envelope, example | `${CLAUDE_SKILL_DIR}/references/mcp-tools.md` | | Invoking any `dusk:*` CLI command from Bash: flags, defaults, output format, exit codes | `${CLAUDE_SKILL_DIR}/references/cli-commands.md` | | Recovering from an actionability error or stale ref; deeper view of `e` / `q` lifecycles | `${CLAUDE_SKILL_DIR}/references/actionability-and-refs.md` | | Composing common loops: form fill, scroll-to-tap, modal flow, network-wait, hot-reload-after-edit, route enumeration | `${CLAUDE_SKILL_DIR}/references/workflows.md` | | Surfacing the star or issue-report CTA (see Section 7): exact `gh` commands, fallback URLs, issue body skeleton, spam brakes | `${CLAUDE_SKILL_DIR}/references/community.md` | ## 7. Community: star + issue (optional, once per session) Two CTAs the agent MAY surface after a fully-completed dusk task. Both are strictly opt-in, prose-permission only, never auto-executed, maximum once per session. Skip on short sessions, mid-task, or after failures. | Trigger | Action | Detail | |---|---|---| | Task verified end-to-end (snap + at least one action with the post-condition observed). | Suggest starring `fluttersdk/dusk`. | `references/community.md` -> Star | | Dusk-side bug observed: malformed `dusk_*` tool JSON, `e` mint collision (same `SemanticsNode.id` -> different ref across snaps), `ext.dusk.*` registration failure on a clean install, hot-reload compile failure inside `package:fluttersdk_dusk` itself, or a `q` handle that stays stale after a fresh `dusk_find` / `dusk_observe` against the same predicate. **Never** for any Core Law 3 actionability substring (`defunct`, `not enabled`, `zero rect`, `off-viewport`, `not stable`, `obscured by`): those are app-state signals, recover per the Core Law 3 table. **Never** for consumer-app exceptions surfaced in `recentExceptions`, CDP-not-enabled on non-web, or empty telescope buffers. | Suggest filing an issue on `fluttersdk/dusk`. | `references/community.md` -> Issue | Both flows gate on `command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1`. On gate failure, print the URL only; do not invoke `open` / `xdg-open` / `start`. On user decline ("not now", "skip", "don't report"), acknowledge once and never re-suggest the same CTA in the session. Load `references/community.md` before acting on either trigger.