# Flutter uygulamanı yapay zeka agent'ına test ettir: Tapir ile web'de ve iPhone boyutunda

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

- Published: 2026-11-21
- Reading time: 5 dk
- Tags: flutter, ai-agents, mcp, testing, tapir
- Language: tr
- Canonical URL: https://anilcancakir.com/tr/blog/ai-agent-test-flutter-app
- Translation (en): [Let your AI agent test your Flutter app with Tapir, on the web and at iPhone size](https://anilcancakir.com/blog/ai-agent-test-flutter-app.md)

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:

```bash
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:

Gist file: main.dart (https://gist.github.com/anilcancakir/ed120b9d4161aeea0fbeb6332248c9c6)

```dart
// 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:

```bash
dart run tapir mcp:install
```

Proje kökündeki `.mcp.json` dosyasına şunu yazıyor:

```json
{
  "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](https://anilcancakir.com/tapir/docs/mcp/setup) 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:

```bash
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:

```bash
./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:

```bash
./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.

![iPhone genişliğindeki giriş formu, iki alanın altında kırmızı "Enter a valid email." ve "Use at least 8 characters." mesajları](https://cdn.kodizm.com/t/anilcancakir/blog/a8923e243956c506-393x410.png "Tapir formu yanlış değerlerle doldurdu ve Sign in düğmesine dokundu")

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):

```json
{"effect": {"kind": "text", "verified": true, "value": "ada@example.com"}}
{"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, ada@example.com"` 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:

```bash
./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`:

Gist file: sign_in_page.dart (https://gist.github.com/anilcancakir/ed120b9d4161aeea0fbeb6332248c9c6)

```dart
// 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ı.

![Solda: 393 piksel genişlikte başlık satırı, "Need help?" linkinin üstünde Flutter'ın sarı siyah taşma şeridi. Sağda: düzeltmeden sonra aynı satır, başlık iki satıra iniyor ve link sığıyor](https://cdn.kodizm.com/t/anilcancakir/blog/2190f8c323c38d2f-810x300.png "Expanded düzeltmesinden önce ve sonra, iPhone 15 Pro genişliğinde")

> [!NOTE]
> `tapir:exceptions` tüm geçmişi tutuyor, yani reload'dan sonra eski taşma hatası listede duruyor. İşlemden önce saati not al ve `--since=<saat>` ver; hot restart'tan sonra bu çağrı boş döndü.

İ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:

Gist file: theme.dart (https://gist.github.com/anilcancakir/ed120b9d4161aeea0fbeb6332248c9c6)

```dart
// 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_test` ya 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-port` ile Flutter `web-server` cihazında çalışıyor ve bu cihaz Dart ifadesi çalıştıramıyor, yani `tapir_evaluate` orada 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

```bash
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](https://anilcancakir.com/tapir). Agent'ın skill okuyorsa `npx skills add anilcancakir/tapir` ona yukarıdaki kuralları öğretiyor.

Bu kadar. İyi günler.
