terminal FlutterSDK Dusk

Flutter E2E driver for LLM agents

Name: Dusk
Author: FlutterSDK

Drive a running Flutter app over VM Service extensions and MCP. Snapshot the Semantics tree, drive any gesture, capture screenshots, observe live state, all from one CLI and one stdio MCP server.

Snap, tap, type, drag, scroll, and find widgets by ref over ext.dusk.*. No flutter_test harness, no isolate spawn, no separate test process.

Read the docs View on pub.dev

terminal

flutter pub add fluttersdk_dusk
dart run fluttersdk_dusk dusk:snap

Powered by our Sponsors

Helping us build the future of Flutter development.

Become a Sponsor arrow_forward

Why dusk?

Attach to the running app.

End-to-end testing on Flutter splits into three buckets, and dusk fills the gap none of them cover. Same ext.dusk.* extensions back human CLI calls and agent MCP tool calls, so the contract is identical at every layer.

extension

Dusk in your app

Best for

Wire dusk into the running app for hot integration tests. The plugin registers ext.dusk.* VM Service extensions so every CLI and MCP call routes through the live isolate.

flutter pub add fluttersdk_dusk
// then: DuskPlugin.install()

terminal

Dusk CLI

Best for

Drive a running app from the terminal, locally or in CI. The pure-Dart CLI wrapper attaches over VM Service and pipes results to stdout, so any shell pipeline or CI runner can script it.

dart run fluttersdk_dusk dusk:snap

smart_toy

Dusk MCP

Best for

AI agents (Claude Code, Cursor, Windsurf, Copilot). One stdio MCP server exposes every dusk extension as a tool call, so the agent reads Semantics and drives gestures with the same contract the human CLI uses.

dart run fluttersdk_artisan mcp:install

verified

Every gesture passes a 5-step actionability gate: defunct, enabled, zero-rect, off-viewport, stable, receives-events. If a widget fails any check, dusk surfaces which one and why, so the agent can fix the test instead of guessing at flake.

flutter_test and integration_test drive an in-process WidgetTester inside a test harness. They are the right tool for unit-shaped widget assertions and headless CI smoke; they are not the right tool for an agent reasoning about the running app you are looking at.

patrol wraps integration_test with native automation, so it inherits the same test-session model. maestro drives the OS accessibility layer from outside the app, with no Flutter-level knowledge. Both serve scripted scenarios; neither attaches to your debug build mid-feature.

Dusk is for the running app. You attach to the live isolate, snap the Semantics tree, drive a gesture, capture a screenshot, read live state. You do not write a test file, you do not set up a runner, you do not wait for a build. The agent has eyes and hands the moment DuskPlugin.install() registers its extensions.

What Dusk ships

Every layer, drivable.

Three surfaces, one contract. The same ext.dusk.* extensions back human terminals, AI agents, and CI runners.

flutter_dash Built for Flutter testing

Live attach to the running app, no harness, no isolate spawn, no separate test process.

verified

5-step actionability gate

Every gesture clears defunct, enabled, zero-rect, off-viewport, stable, and receives-events checks before firing, so a failed step names which gate it tripped.

cable

VM Service extensions

Registers ext.dusk.* directly on the live isolate. No isolate spawning, no separate test process, no harness boot.

bolt

Hot reload + snap fused round-trip

One command writes the FIFO, polls the log, waits for the reload signal, then snaps the post-reload Semantics tree. Edit, reload, observe in a single shell call.

smart_toy Built for AI agents

Structured Semantics over a stdio MCP server. Deterministic refs, no vision models, no scraped pixels.

hub

31 MCP tools

Claude Code, Cursor, Windsurf, Copilot. One stdio server exposes every dusk extension as a deterministic tool call backed by ref-based widget addressing.

tag

e/q dual token system

Playwright Locator parity for Flutter. e<N> refs are snapshot-frozen; q<N> queries re-resolve against the live tree on every call.

psychology

LLM-friendly

No vision models required. Dusk operates on the structured Semantics data Flutter already exposes, so the agent reads a typed tree instead of guessing at pixels.

developer_board Built for CI

Pure-Dart wrappers, scripted viewport and device emulation, framework-agnostic plug-in points.

terminal

Pure-Dart CLI wrapper

No dart:ui import. The wrapper runs on the Dart VM alone, so CI runners without a display attach over VM Service like any other shell tool.

devices

CDP layer

Chrome DevTools Protocol drives viewport and device emulation from the script: dusk:resize sizes the window, dusk:device swaps the user agent.

extension

Framework-agnostic enricher API

Magic and Wind plug into DuskPlugin.enrichers. Each enricher decorates the snapshot with its own facts, so a Magic state node or a Wind layout hint lands next to the widget that owns it.

Drive it

dusk:snap in your terminal.

One CLI, 32 commands, every dusk:* extension reachable from the terminal. The agent calls the same surface over MCP.

dart run fluttersdk_dusk dusk:snap

$ dart run fluttersdk_dusk dusk:snap
[SNAP] Semantics tree captured (48 nodes, 12ms)
refs/e7   Button "Add to cart"           enabled, hittable
refs/e8   TextField "email"              enabled, focused
refs/e9   ListView                       scrollable, 24 children
refs/q14  Container "card-2"             snapshot-frozen ref

$ dart run fluttersdk_dusk dusk:tap --ref=e7
[TAP ] dusk:tap --ref=e7 → ok in 41ms

$ dart run fluttersdk_dusk dusk:screenshot --out=demo.png
[SHOT] screenshot saved to demo.png (1280x720)

One surface, two callers, identical contract

Every CLI command compiles down to a single ext.dusk.* call over VM Service. No isolate spawning, no separate test harness, no second source of truth.

The stdio MCP server calls the exact same extensions. Every gesture passes the same 5-step actionability gate before it fires; every snapshot returns the same Semantics tree.

What you see in dusk:snap is what the agent sees: structured refs, deterministic ordering, the same actionability metadata on every node.

Read the CLI docs arrow_forward

MCP-first

31 MCP tools for LLM agents.

A single stdio server exposes every dusk extension as a typed tool call. The protocol is LLM-friendly by design: structured Semantics in, ref-addressed gestures out, no vision models required. Wire it once with claude mcp add, or drop the same command into .mcp.json for Cursor and Windsurf.

dusk:snap read

Captures the live Semantics tree as a typed YAML buffer with ref-addressed nodes.

dusk:tap act

Fires a tap gesture against a ref after the 5-step actionability gate clears.

dusk:type act

Sends keyboard input into a ref-addressed text field, focus and IME aware.

dusk:drag act

Drags a ref across an offset with configurable velocity for slider and reorder flows.

dusk:scroll act

Scrolls a viewport until a target ref enters view or a delta exhausts.

dusk:screenshot read

Writes a PNG of the current frame to a path the agent supplies.

dusk:wait_for gate

Waits for a ref to exist and pass actionability, with a typed timeout result.

dusk:hot_reload_and_snap compose

Writes the reload FIFO, polls the log for the reload signal, then snaps the post-reload tree.

dusk:resize env

Resizes the Chrome viewport over CDP, no reload needed.

dusk:device env

Emulates a named device profile over CDP (user agent, DPR, touch).

dusk:logs observe

Tails VM log output, filtered by level and source isolate.

dusk:probe gate

Runs the 5-step actionability gate on a single ref and reports which step it tripped.

Wire it into Claude Code in one command:

terminal

claude mcp add --transport stdio fluttersdk -- dart run fluttersdk_artisan mcp:serve

Framework-agnostic enricher API

Magic and Wind plug straight in.

Snapshots stay framework-neutral by default; the apps that need richer data wire their own facts in.

Dusk treats the snapshot as a public contract. The base DuskPlugin emits the Semantics tree, layout rects, and stable refs; the DuskPlugin.enrichers list invites other packages to decorate nodes with their own facts before the snapshot serializes.

Magic ships a MagicEnricher that annotates each widget with the Magic model, gate, and event lifecycle frames feeding it. Wind ships a WindEnricher that surfaces the resolved Tailwind-style utility classes and design tokens on every styled node. Both sit behind the same enricher contract, so a Flutter app on either stack gets agent-ready snapshots without touching dusk source.

The enricher list is open. Bring your own router, your own state container, your own analytics layer; the snapshot inherits the new facts the moment the plugin registers.

main.dart

DuskPlugin.install(enrichers: [MagicEnricher(), WindEnricher()])

auto_awesome

Magic

The reactive app framework. MagicEnricher surfaces model, gate, and event frames inside every dusk snapshot.

Read the architecture

air

Wind

The utility-first UI kit. WindEnricher annotates each styled node with its resolved utilities and tokens.

Explore Wind

Compared to

End-to-end testing on Flutter splits three ways.

Each of these tools owns a different slice of the surface. Dusk picks the slice the others leave open: the running app, observed live, with an agent-native contract on top.

Tool	Drives	Test harness	LLM-agent surface
`flutter_test` / `integration_test`	In-process WidgetTester	Yes	None
`patrol`	Native + integration_test	Yes	`patrol_mcp` (test sessions only)
`maestro`	OS accessibility layer	No	Maestro MCP (cloud)
`fluttersdk_dusk`	Running Flutter app over VM Service	No	31 MCP tools, native

Dusk is for the running app. The same ext.dusk.* VM Service extensions back every human CLI invocation and every agent MCP tool call, so the contract is identical at every layer.

You attach to the live isolate, and the human at the keyboard and the agent over stdio reach for the exact same primitives, no separate scripting layer in between.

Inspiration

Borrowed from the best.

Dusk inherits ideas from a generation of agent-first browser tooling. The shape of the API, the ref token discipline, and the structured-data-over-vision posture all trace back to these four.

format_quote

LLM-friendly. No vision models needed, operates purely on structured data.

Playwright MCP

github.com/microsoft/playwright-mcp

format_quote

Scripts give precision. Agents give flexibility. Stagehand gives both.

Stagehand

stagehand.dev

format_quote

Auto-wait and web-first assertions, no artificial timeouts, no flaky tests.

Playwright

playwright.dev

format_quote

Think of it as USB-C for AI integrations.

Anthropic MCP

modelcontextprotocol.io

Drive your Flutter app today.

One install, one CLI, one MCP server. Attach to the running app over VM Service extensions and let humans and agents share the same primitives.

terminal

flutter pub add fluttersdk_dusk
dart run fluttersdk_dusk dusk:snap

Star on GitHub menu_book Read the docs