Flutter uygulamanı yapay zeka agent'ına test ettir: Tapir ile web'de ve iPhone boyutunda
- published
- reading
- 5 dk
- author
- Anılcan Çakır
- lang
- tr en
- format
- markdown
Tapir, Claude Code, Cursor ya da Codex'in çalışan Flutter uygulamanı MCP üzerinden kullanmasını sağlıyor: ref'li snapshot, gerçek dokunma ve yazma, sonucu söyleyen effect bloğu ve uygulamanın hataları. Web görünümünü iPhone genişliğine indir, agent masaüstünün gizlediği yerleşim hatalarını yakalasın.
On this page
Bugün yapay zeka agent'ının, yazdığı kodu çalışan Flutter uygulamasında kendisinin kontrol etmesini göstereceğim. Sadece kodu okumayacak: dokunacak, yazacak, ekran görüntüsü alacak ve uygulamanın verdiği hataları okuyacak. Hem web'de hem iPhone genişliğinde.
Flutter 3.50 11 Kasım'da duyuruldu ve resmi agent eklentileriyle geldi. Bu eklentilerin bir kuralı, agent lib/ altında bir dosyayı her değiştirdiğinde MCP sunucusu üzerinden hot reload yapıyor. Güzel. Ama reload sadece kodun derlendiğini söyler. Düğmenin çalıştığını ya da başlığın telefonda hâlâ sığdığını söylemez. Bugüne kadar benim döngüm şöyleydi: hot reload, ekran görüntüsü al, PNG'yi sohbete sürükle, widget kodunu yapıştır, düğme neden bir şey yapmıyor diye sor. Her seferinde.
Tapir bu döngüyü kapatıyor. Debug build'in içinde çalışıyor; Claude Code, Cursor ya da Codex canlı uygulamayı onun MCP sunucusu üzerinden kullanıyor. Bir sınırı var, sonda onu da açıkça söyleyeceğim.
Bu yazıdan alacakların:
- Bir Flutter uygulamasına kurulu ve agent'ına bağlı Tapir
- Agent'ın ne gördüğü: her kontrol için bir ref taşıyan kısa bir snapshot
- Gerçek bir form doldurma ve dokunma; agent'ın dokunuşun işe yaradığını nasıl anladığı
- Masaüstü tarayıcının gizlediği, iPhone boyutundaki ekranın gösterdiği bir yerleşim hatası
Başlayalım.
Tapir'i kur#
İki komut:
flutter pub add tapir dowel
dart run tapir tapir:install
tapir:install senin yerine lib/main.dart dosyasını düzenliyor: import'u ekliyor ve TapirPlugin.install() çağrısını !kReleaseMode koşulunun içine koyuyor. Ayrıca hızlı CLI sarmalayıcısı ./bin/dowel dosyasını oluşturuyor ve Tapir'i, üzerinde çalıştığı CLI ve MCP sunucusu olan Dowel'a eklenti olarak kaydediyor. Kurulumdan sonra benim main.dart dosyam:
// lib/main.dart
import 'package:flutter/foundation.dart' show kReleaseMode;
import 'package:material_ui/material_ui.dart';
import 'package:tapir/tapir.dart';
import 'sign_in_page.dart';
import 'theme.dart';
void main() {
WidgetsFlutterBinding.ensureInitialized();
// Debug and profile builds only: anyone who reaches the VM Service of a build that carries tapir can drive it.
if (!kReleaseMode) {
TapirPlugin.install();
}
runApp(const SignInDemoApp());
}
/// The demo app: one sign-in page and the welcome page it opens.
class SignInDemoApp extends StatelessWidget {
const SignInDemoApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Sign in demo',
debugShowCheckedModeBanner: false,
theme: appTheme,
darkTheme: appTheme,
themeMode: ThemeMode.dark,
home: const SignInPage(),
);
}
}
Bu koşul önemli. Debug ve profile build'ler Tapir'i taşır, release build'e girmez. Koşul olmazsa uygulamanın VM Service'ine erişen herkes uygulamanı kullanabilir.
Agent'ını bağla#
Bir komut daha MCP kaydını yazıyor:
dart run tapir mcp:install
Proje kökündeki .mcp.json dosyasına şunu yazıyor:
{
"mcpServers": {
"dowel": {
"command": "./bin/dowel",
"args": ["mcp:serve"],
"cwd": "."
}
}
}
Claude Code .mcp.json dosyasını kendiliğinden yeniden okumuyor, bu yüzden bir kez /mcp reconnect dowel çalıştır. Cursor, VS Code, Windsurf ve Codex aynı kaydı okuyor; MCP kurulum sayfasında her biri için bir satır var. Sunucudan araç listesini istediğimde 40 tapir_* aracı döndü: tapir_snap, tapir_tap, tapir_fill, tapir_screenshot, tapir_exceptions ve diğerleri.
Uygulamayı Tapir ile başlat#
Uygulamayı düz flutter run ile değil, Tapir ile başlatman gerekiyor. Çünkü her komut, Tapir'in kaydettiği oturuma bağlanıyor:
dart run tapir start --device=chrome --cdp-port=9333
CDP portu, Tapir'in Chrome üzerinden ekran görüntüsü almasını ve görüntü alanını yeniden boyutlandırmasını sağlıyor; birazdan buna ihtiyacımız olacak. Native bir hedefte bunun yerine cihazı veriyorsun (--device=macos, bir iOS simülatörünün id'si, bir Android seri numarası). Bu yazıda web'de kaldım, çünkü göstermek istediğim hata için dar bir ekran yeterli.
Örneğim küçük bir giriş sayfası: e-posta, şifre, bir "Sign in" düğmesi ve başlığın yanında bir "Need help?" linki. İçinde bilerek bıraktığım bir hata var.
Agent ne görüyor#
Agent'ın ilk yaptığı şey snapshot almak. Aynı çağrıyı terminalden yapıyorum ki agent'ın eline ne geçtiğini gör:
./bin/dowel tapir:snap --interactiveOnly
- button "Need help?" [ref=e1]
- textbox "Email" [ref=e2]
typeable: true
- textbox "Password" [ref=e3]
typeable: true
- button "Sign in" [ref=e4]
Bunu kalabalığın fotoğrafı yerine kapıdaki davetli listesi gibi düşün. Agent bir ekran görüntüsünden piksel konumu tahmin etmiyor. Uygulamanın Semantics ağacını okuyor ve her kontrol üzerinde işlem yapabileceği kısa bir ref alıyor (e1, e2, ...). Beş satır bağlamda neredeyse yer kaplamıyor, yani agent her adımdan sonra yeni bir snapshot alabilir.
Bırak kullansın#
Şimdi agent formu yanlış değerlerle dolduruyor ve düğmeye dokunuyor:
./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"
✓ Filled e2
✓ Filled e3
✓ Tapped e4 (target unchanged)
- textbox "Email": "ada" [ref=e2]
typeable: true
- text "Enter a valid email."
- textbox "Password": "•••••" [ref=e3]
typeable: true
- text "Use at least 8 characters."
Bunlar widget ağacına giden gerçek dokunma ve tuş olayları; doğrulayıcılar bir insan kullanırken nasıl çalışıyorsa öyle çalışıyor.

Yeşil tik sadece olayın Tapir'den çıktığını söyler, widget'ın onu aldığını söylemez. Bu yüzden agent effect bloğunu okuyor (--json ile basılıyor):
{"effect": {"kind": "text", "verified": true, "value": "[email protected]"}}
{"effect": {"kind": "treeChanged", "changed": false, "routeChanged": true}}
İlki tutan bir doldurma. İkincisi doğru değerlerle "Sign in" düğmesine dokunuş: düğmenin kendisi değişmedi ama yeni bir route açıldı (routeChanged, Tapir 1.1.0 ile geldi). Bir sonraki snapshot'ta text "Welcome back, [email protected]" görünüyor.
Peki agent erişemeyeceği bir şeye dokunmaya çalışırsa? Tapir dokunmadan önce widget'ın etkin, ekranda, sabit ve üstü kapalı olmadığını kontrol ediyor. Karşılama sayfası öndeyken eski "Sign in" ref'ine bir daha dokundum:
Widget ref=e4 is not actionable: obscured by other widget (top=_RenderInkFeatures)
Ret mesajı sebebi söylüyor (obscured by, not enabled, off-viewport, not stable). Böylece agent körlemesine tekrar denemiyor ya da bir Future.delayed ekleyip umut etmiyor.
Sadece iPhone boyutundaki ekranın gösterdiği hata#
Masaüstündeki Chrome penceremde sayfa düzgün görünüyor ve tapir:exceptions boş liste dönüyor. Şimdi ona iPhone 15 Pro genişliğini verelim:
./bin/dowel tapir:resize_viewport --width=393 --height=852 --dpr=2.0 --mobile --touch --hold
--hold boyutu agent çalıştığı sürece koruyor, bu yüzden arka planda çalıştır (tapir:device_profile --preset=iphone-15-pro aynı boyutu sadece tek komut boyunca uyguluyor). Sonra yeni bir 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
Agent'ın bunu bulmak için ekran görüntüsüne ihtiyacı olmadı. Snapshot hatayı en üste koyuyor ve ekrandan dışarı itilen widget'ı işaretliyor. Başlık ve link bir Row içinde, başlığın alt satıra geçecek yeri yok. Çözüm tek bir widget, başlığın etrafına Expanded:
// lib/sign_in_page.dart
import 'package:material_ui/material_ui.dart';
import 'theme.dart';
/// Email and password form that opens [WelcomePage] once both fields pass validation.
class SignInPage extends StatefulWidget {
const SignInPage({super.key});
@override
State<SignInPage> createState() => _SignInPageState();
}
class _SignInPageState extends State<SignInPage> {
final GlobalKey<FormState> _formKey = GlobalKey<FormState>();
final TextEditingController _email = TextEditingController();
final TextEditingController _password = TextEditingController();
@override
void dispose() {
_email.dispose();
_password.dispose();
super.dispose();
}
void _submit() {
if (!_formKey.currentState!.validate()) {
return;
}
Navigator.of(context).push(
MaterialPageRoute<void>(
builder: (BuildContext context) => WelcomePage(email: _email.text.trim()),
),
);
}
@override
Widget build(BuildContext context) {
return Scaffold(
body: SafeArea(
child: Center(
child: ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 480),
child: Padding(
padding: const EdgeInsets.all(24),
child: Form(
key: _formKey,
child: Column(
mainAxisSize: MainAxisSize.min,
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
const _Header(),
const SizedBox(height: 24),
TextFormField(
controller: _email,
keyboardType: TextInputType.emailAddress,
decoration: const InputDecoration(labelText: 'Email'),
validator: _validateEmail,
),
const SizedBox(height: 16),
TextFormField(
controller: _password,
obscureText: true,
decoration: const InputDecoration(labelText: 'Password'),
validator: _validatePassword,
),
const SizedBox(height: 24),
FilledButton(
onPressed: _submit,
child: const Text('Sign in'),
),
],
),
),
),
),
),
),
);
}
static String? _validateEmail(String? value) {
final String email = value?.trim() ?? '';
if (email.isEmpty) {
return 'Enter your email.';
}
return email.contains('@') ? null : 'Enter a valid email.';
}
static String? _validatePassword(String? value) {
return (value ?? '').length < 8 ? 'Use at least 8 characters.' : null;
}
}
/// The title row: the page name and a help link side by side.
class _Header extends StatelessWidget {
const _Header();
@override
Widget build(BuildContext context) {
return Row(
children: [
Expanded(
child: Text(
'Sign in to your team workspace',
style: Theme.of(context).textTheme.titleLarge?.copyWith(color: ink),
),
),
const SizedBox(width: 12),
TextButton(
onPressed: () {},
child: const Text('Need help?'),
),
],
);
}
}
/// Shown after a successful sign-in.
class WelcomePage extends StatelessWidget {
const WelcomePage({
super.key,
required this.email,
});
final String email;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(backgroundColor: surface),
body: Center(
child: Text(
'Welcome back, $email',
style: Theme.of(context).textTheme.titleMedium?.copyWith(color: ink),
),
),
);
}
}
tapir:hot_reload_and_snap uygulamayı yeniden yüklüyor ve yeni snapshot'ı, ekranı ve son hataları tek seferde döndürüyor. overflow işareti snapshot'tan kalktı.

İstediğim döngü buydu: agent kodu değiştiriyor, yeniden yüklüyor, ekranı kullanıcının ekranı boyutunda kontrol ediyor ve ancak ondan sonra bitti diyor.
Tema#
Ekran görüntüleri koyu, çünkü örnek bu blogun renklerinde koyu bir tema kullanıyor. Kendi kopyanın aynı görünmesini istersen dosya burada:
// lib/theme.dart
import 'package:material_ui/material_ui.dart';
const Color surface = Color(0xFF15191F);
const Color panel = Color(0xFF22272E);
const Color line = Color(0xFF373E47);
const Color accent = Color(0xFF539BF5);
const Color ink = Color(0xFFCDD9E5);
const Color faint = Color(0xFF8B949E);
const Color danger = Color(0xFFF47067);
/// A dark theme in the blog's palette, so screenshots sit calmly on a dark page.
final ThemeData appTheme = ThemeData(
brightness: Brightness.dark,
scaffoldBackgroundColor: surface,
colorScheme: const ColorScheme.dark(
surface: surface,
primary: accent,
onPrimary: surface,
onSurface: ink,
error: danger,
),
inputDecorationTheme: InputDecorationTheme(
filled: true,
fillColor: panel,
hintStyle: const TextStyle(color: faint),
labelStyle: const TextStyle(color: faint),
enabledBorder: OutlineInputBorder(
borderRadius: BorderRadius.circular(8),
borderSide: const BorderSide(color: line),
),
focusedBorder: OutlineInputBorder(
borderRadius: BorderRadius.circular(8),
borderSide: const BorderSide(color: accent),
),
errorBorder: OutlineInputBorder(
borderRadius: BorderRadius.circular(8),
borderSide: const BorderSide(color: danger),
),
focusedErrorBorder: OutlineInputBorder(
borderRadius: BorderRadius.circular(8),
borderSide: const BorderSide(color: danger),
),
),
filledButtonTheme: FilledButtonThemeData(
style: FilledButton.styleFrom(
backgroundColor: accent,
foregroundColor: surface,
minimumSize: const Size.fromHeight(48),
shape: RoundedRectangleBorder(
borderRadius: BorderRadius.circular(8),
),
),
),
);
Tapir'in yanlış araç olduğu yerler#
- Regresyon test takımın değil. Tapir canlı bir uygulamayı kullanıyor, test dosyası yazmıyor. Asla bozulmaması gereken akışlar için CI'da
integration_testya da Patrol kullanmaya devam et. Resmi Dart ve Flutter MCP sunucusunda bir Flutter Driver aracı ve bir kullanıcı yolculuğunu driver testine çeviren bir prompt var; istediğin bir test dosyasıysa o daha yakın. - Sadece debug ve profile build'ler. Release build'de Tapir yok, bilerek.
- Web oturumu bir şeyden vazgeçiyor.
--cdp-portile Flutterweb-servercihazında çalışıyor ve bu cihaz Dart ifadesi çalıştıramıyor, yanitapir_evaluateorada hata dönüyor. Ona ihtiyacın varsa portu vermeden başlat. - Bu taşmayı bir widget testi de yakalayabilir, o genişlikte bir test yazarsan. Tapir, agent ekranı daha kurarken, henüz kimsenin test yazmadığı ekranlar için.
Kurulum#
flutter pub add tapir dowel
dart run tapir tapir:install
dart run tapir mcp:install
Dokümanlar, tüm komutlar ve MCP araçlarının tam listesi Tapir sayfasında. Agent'ın skill okuyorsa npx skills add anilcancakir/tapir ona yukarıdaki kuralları öğretiyor.
Bu kadar. İyi günler.