cd /news/ai-agents/let-your-ai-agent-test-your-flutter-… · home › topics › ai-agents › article
[ARTICLE · art-173557] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

Let your AI agent test your Flutter app with Tapir, on the web and at iPhone size

A developer built Tapir, a Flutter package that runs inside a debug build and exposes an MCP server so AI coding agents can test apps directly. The tool provides a Semantics snapshot with a ref for every control, real taps and typing, an effect block reporting whether an action worked, and captured render errors; resizing the viewport to iPhone 15 Pro dimensions (393x852) surfaced a RenderFlex overflow of 67 pixels that was invisible at desktop width. Installation patches main.dart behind !kReleaseMode and registers a dowel entry in .mcp.json, exposing 40 tapir_* tools to Claude Code, Cursor, VS Code, Windsurf and Codex.

key takeaway

Tapir's MCP server gives agents a Semantics snapshot with refs plus an effect block, and resizing the viewport to 393x852 at dpr 2.0 exposed a 67-pixel RenderFlex overflow that was invisible at desktop width.

by read3 min views13 publishedNov 21, 2026

Flutter 3.50 shipped official agent plugins, and one of their rules hot reloads the app every time the agent edits a file under lib/. That's good. But a reload only says the code compiled. It doesn't say the button works, or that the header still fits on a phone.

My loop used to be: hot reload, take a screenshot, drag the PNG into the chat, paste the widget source, ask why the button does nothing. Today, I'll show you how I let the agent do that part itself.

TL;DR: Tapir runs inside your debug build and gives your agent an MCP server: a Semantics snapshot with a ref for every control, real taps and typing, an effect block that says whether it worked, and the errors the app raised. Shrink the web view to iPhone width and the agent finds the layout bugs a desktop window hides.

flutter pub add tapir dowel
dart run tapir tapir:install
dart run tapir mcp:install

tapir:install patches main.dart and puts TapirPlugin.install() behind !kReleaseMode, so a release build carries none of it:

mcp:install writes a dowel entry into .mcp.json (./bin/dowel mcp:serve). In Claude Code run /mcp reconnect dowel once; Cursor, VS Code, Windsurf and Codex read the same entry. The server answered my tool list request with 40 tapir_* tools.

Then start the app through Tapir, so every command finds the session:

dart run tapir start --device=chrome --cdp-port=9333

A snapshot is the first call. Here is the same thing from the terminal:

- button "Need help?" [ref=e1]
- textbox "Email" [ref=e2]
  typeable: true
- textbox "Password" [ref=e3]
  typeable: true
- button "Sign in" [ref=e4]

It's a guest list at the door instead of a photo of the crowd. No pixel guessing; every control has a ref the agent can act on, and five lines cost almost nothing in context.

./bin/dowel tapir:fill --ref=e2 --text="ada"
./bin/dowel tapir:fill --ref=e3 --text="short"
./bin/dowel tapir:tap --ref=e4
./bin/dowel tapir:snap --grep="Enter|Use at"
✓ Tapped e4 (target unchanged)
- textbox "Email": "ada" [ref=e2]
  - text "Enter a valid email."
- textbox "Password": "•••••" [ref=e3]
  - text "Use at least 8 characters."

A green tick only says the event left Tapir, so the agent reads effect (with --json). With valid values the tap on "Sign in" answered {"changed": false, "routeChanged": true}: the button didn't change, but a new page opened. And a tap on something covered is refused with a reason the agent can act on:

Widget ref=e4 is not actionable: obscured by other widget (top=_RenderInkFeatures)

At desktop width, tapir:exceptions was empty. Then I gave the page iPhone 15 Pro's width:

./bin/dowel tapir:resize_viewport --width=393 --height=852 --dpr=2.0 --mobile --touch --hold

The next snapshot:

✗ ⚠ 1 render error(s) captured on this screen (run tapir:exceptions / tapir_exceptions for full detail):
✗   - overflow: A RenderFlex overflowed by 67 pixels on the right.
- button "Need help?" [ref=e1]
  overflow: true

The title and the help link sit in a Row, and the title has no room to wrap. One Expanded fixes it, and tapir:hot_reload_and_snap confirms it in one round trip:

integration_test or Patrol in CI. The official Dart and Flutter MCP server has a Flutter Driver tool that can turn a user journey into a driver test, if a test file is what you want.--cdp-port session runs on the web-server device, which can't evaluate Dart expressions. How do you check your agent's UI changes today: screenshots in the chat, a test suite, or by hand?

The full walkthrough, with the dark theme file and the notes on tapir:exceptions --since, is on my blog: Let your AI agent test your Flutter app with Tapir.

── more in #ai-agents 4 stories · sorted by recency
── more on @tapir 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/let-your-ai-agent-te…] indexed:0 read:3min 2026-11-21 · —