I Built Dusk: Playwright MCP, but for Flutter Apps

Last week I watched my AI agent try to test a Flutter screen. It wrote a test file, ran flutter test, copied the stack trace back into the prompt, pasted a screenshot, and called it a workflow. It was slow, and it was guessing.

On the web, agents do not work like that anymore. Playwright MCP gives them an accessibility tree to read and stable refs to act on. 33k stars, no screenshot guessing. Flutter never had that layer.

So I built Dusk.

The problem

End-to-end testing on Flutter has always been a stitched-together ritual.

flutter_driver ships a one-off socket protocol and is on the legacy track. integration_test runs in-process against a simulated WidgetTester, but you write a test file, build, run, and wait. Maestro is nice but pays around 3 seconds per action. Patrol is powerful but tends to be unstable on CI.

The deeper issue is the loop. An agent that wants to drive your app reaches for ad hoc flutter test runs, copies stack traces by hand, and pastes screenshots back. There is no live connection between the agent and the running app.

// The old loop: write a test file, build, run, wait, read the failure, repeat.

testWidgets('checkout flow', (tester) async {

  await tester.tap(find.byKey(const Key('checkout')));

  await tester.pumpAndSettle();

  // ...and you still rebuild and rerun the whole thing to see what happened.

});

How Dusk handles it

Dusk attaches to a running Flutter app over VM Service extensions. No test file, no flutter_test harness, no build step. You start your app, attach, and the agent has eyes and hands.

First it snapshots the Semantics tree:

dart run fluttersdk_dusk dusk:snap

That returns a YAML tree with stable [ref=eN] tokens. Every action targets a ref, so there is no brittle XPath and no coordinate guessing.

dusk:tap --ref=e7

dusk:type --ref=e3 --text "[email protected]"

dusk:screenshot

The same contracts power your terminal and your AI agent. dusk:tap --ref=e7 on the CLI and dusk_tap as an MCP tool reach the exact same code path. 32 CLI commands and 31 MCP tools: snap, tap, type, scroll, drag, observe, screenshot, and a hot-reload-and-snap round trip that returns the new tree, a screenshot, and any exceptions in one call.

Why it does not flake

Every gesture passes a 6-step actionability gate before it runs: not defunct, enabled, non-zero rect, on-viewport (it auto-scrolls), stable across 2 frames, and actually hit-testable. So your agent never taps a button that is not really there yet.

This is the part that turns "drive the app" from a demo into something you trust. The boring check is the whole point.

Where it fits

Dusk does not replace your test suite. It owns a different niche: the unscripted, running app.

Get started

flutter pub add fluttersdk_dusk

dart run fluttersdk_dusk dusk:install

dusk:install patches lib/main.dart behind kDebugMode and scaffolds the CLI. Release builds tree-shake the entire driver across web, desktop, and mobile, so Dusk never ships to production.

Wire it into your agent with one more command:

dart run fluttersdk_dusk mcp:install

That registers the stdio MCP server for Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible agent. Dusk also ships its own agent skill, so the agent learns the ref grammar and the tool surface, not just the syntax.

What I learned

Two things stuck with me.

First, the accessibility tree is the right interface for agents on Flutter just as much as on the web. Semantics nodes are stable, cheap, and already there. Screenshots are the slow, expensive fallback, not the default.

Second, the actionability gate matters more than the tool count. An agent that taps confidently on a widget that has not settled is worse than no automation at all. The 6-step check is what makes the rest usable.

Docs:

If you try it with your agent, I would love to hear what breaks. That's all.