search ESC

Searching…

No results for "".

Type at least 2 characters to search.

Docs

Getting Started

Everything you need to add fluttersdk_dusk to your project, capture your first snapshot, and drive real user gestures from an AI agent or CLI session.

Pick your path

  • Installation: Wire DuskPlugin into a Flutter app and connect the MCP tools to your AI client.
  • Quickstart: 3-step walkthrough from zero to driving the example app with snap, tap, and screenshot.
  • MCP setup: Register the dusk MCP tools in Claude Code, Cursor, Windsurf, or any MCP-compliant client.

What is fluttersdk_dusk?

fluttersdk_dusk is a Flutter E2E driver that gives an AI agent (or a CLI session) eyes and hands over a running Flutter app. It works by registering a set of VM Service extensions under the ext.dusk.* namespace during debug builds, then exposing those extensions as 31 MCP tools and 32 CLI commands. The agent snaps a Semantics YAML to identify widget references, then drives gestures, text input, scrolling, and navigation against those references without any test instrumentation in the production widget tree.

What sets it apart from flutter_test-based integration tests is that it operates against the live running app, not a test-hosted widget. The agent sees the same UI the user sees: real platform chrome, real routing, real auth state. This makes it suitable for exploratory workflows where the agent does not know the widget tree in advance and needs to discover it interactively.

What problem does it solve?

Writing Flutter integration tests requires knowing the widget tree structure upfront, hard-coding find.byKey / find.byType locators, and re-running the full suite every time the UI changes. That works well for regression coverage but poorly for exploratory agent-driven automation, where the agent needs to navigate an unfamiliar UI, read its current state, and take adaptive actions.

fluttersdk_dusk solves this by exporting the Semantics tree as a YAML snapshot with stable e (snapshot-frozen) and re-resolvable q (find-minted) ref tokens. The agent reads the snapshot, locates the target element by semantic role or label, and passes the ref token to an action extension. No test harness setup, no build step, no flutter drive orchestration needed.

When to use it

  • AI agent walkthroughs: give Claude Code, Cursor, or Windsurf hands-on control of your Flutter app so it can inspect, fill forms, and verify flows during development or review.
  • Manual E2E scripting: drive gestures and input from a terminal session without writing widget tests, useful for ad-hoc QA against a staging build.
  • Screenshot pipelines: capture consistent screenshots of specific app states for documentation, design review, or visual regression baselines.
  • CI smoke checks: run a small set of artisan commands in CI to confirm critical paths render without crash, complementing (not replacing) widget unit tests.

Requirements

Dependency Minimum Version Notes
Dart >= 3.4.0 Records, sealed classes, class modifiers.
Flutter >= 3.22.0 RepaintBoundary render-tree walk and Semantics APIs used internally.
fluttersdk_artisan ^0.0.3 Provides the MCP server, CLI framework, and registerExtensionIdempotent.

fluttersdk_dusk requires Flutter. It cannot run on a pure-Dart environment because it synthesizes pointer events against a live widget tree and walks the Semantics tree at runtime. The fluttersdk_artisan CLI is the recommended host for the MCP server and all dusk CLI commands; install it before adding fluttersdk_dusk.

High-level workflow

The typical agent session follows three phases:

1. Capture snapshot   --  dusk_snap / dusk:snap
   Walks the Semantics tree and emits a YAML file with every
   visible widget, its ref token, role, label, bounds, and
   any enricher-contributed metadata (className, MagicRoute, ...).

2. Identify a ref     --  read the YAML / dusk_find
   The agent scans the snapshot for the target widget by label
   or role, reads its ref token (e1, q3, ...).
   dusk_find re-resolves a token without a full re-snap.

3. Drive an action    --  dusk_tap / dusk_type / dusk_scroll / ...
   The agent passes the ref token to an action tool. The extension
   looks up the live element, checks the actionability gate
   (enabled, non-zero-rect, on-viewport), synthesizes the event,
   and returns the result or a structured error.

After an action the agent re-snaps to observe the updated UI and continues the loop. Screenshot requests can be inserted at any point to capture a PNG of the current viewport.

Next steps