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

> Source: <https://dev.to/anilcancakir/let-your-ai-agent-test-your-flutter-app-with-tapir-on-the-web-and-at-iphone-size-2i9i>
> Published: 2026-11-21 00:41:22+00:00

**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.

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](https://anilcancakir.com/blog/ai-agent-test-flutter-app).
