e2e-testing

AI E2E テスト — 8 プラットフォーム、テストコード不要

flutter-skill は、8 プラットフォームで実行中のアプリに AI エージェントを接続する MCP サーバーです。エージェントは、自然言語を通じてスクリーンショットの撮影、要素のタップ、テキストの入力、スクロール、画面遷移、UI ツリーの検査、状態の検証を行います。

対応プラットフォーム

プラットフォーム	セットアップ
Flutter（iOS/Android/Web）	flutter pub add flutter_skill
React Native	npm install flutter-skill-react-native
Electron	npm install flutter-skill-electron
iOS（Swift/UIKit）	SPM: FlutterSkillSDK
Android（Kotlin）	Gradle: flutter-skill-android
Tauri（Rust）	cargo add flutter-skill-tauri
KMP Desktop	Gradle dependency
.NET MAUI	NuGet package

インストール

# npm (recommended)
npm install -g flutter-skill

# Homebrew
brew install ai-dashboad/flutter-skill/flutter-skill

# Or download binary from GitHub Releases

MCP の設定

AI エージェントの MCP 設定（Claude Desktop、Cursor、Windsurf、OpenClaw など）に追加します。

{
  "mcpServers": {
    "flutter-skill": {
      "command": "flutter-skill",
      "args": ["server"]
    }
  }
}

クイックスタート

1. アプリを初期化する（初回のみ）

flutter-skill init

プロジェクトの種類を自動検出し、テストブリッジを使ってアプリにパッチを適用します。

確認: 出力でプロジェクトの種類が検出され、メインのエントリーポイントにパッチが適用されたことを確認します。失敗する場合は、プロジェクトのルートディレクトリにいること、およびフレームワークがサポートされていることを確認してください。

2. 起動して接続する

flutter-skill launch .

確認: 出力に VM Service URI が表示されます（例：ws://127.0.0.1:50000/ws）。URI が表示されない場合は、Flutter または対象のフレームワークがインストールされていること、そしてアプリをコンパイルできることを確認してください。

3. 自然言語でテストする

エージェントは、次の基本ループに従います。

1. screenshot() — 現在の画面を確認します
2. inspect_interactive() — セマンティック参照を持つ、タップや文字入力が可能なすべての要素を検出します
3. tap(ref: "button:Login") — 安定したセマンティック参照を使ってタップします
4. enter_text(ref: "input:Email", text: "[email protected]") — フィールドに入力します
5. wait_for_element(key: "Dashboard") — 画面遷移が成功したことを確認します
6. screenshot() — 最終状態を確認します

inspect_interactive() が要素を返さない場合: スクリーンショットを撮って画面が読み込まれたことを確認し、次に get_logs() でエラーを確認してください。アプリの読み込み中の可能性があるため、少し待ってから再試行してください。

利用可能な MCP ツール

基本操作

ツール	説明
screenshot	現在の画面を画像としてキャプチャします
tap	キー、テキスト、参照、または座標で要素をタップします
enter_text	フィールドにテキストを入力します
scroll	上／下／左／右にスクロールします
swipe	2点間でスワイプ操作を行います
long_press	要素を長押しします
drag	点 A から点 B までドラッグします
go_back	前の画面に戻ります
press_key	キーボードのキーイベントを送信します

検査

ツール	説明
inspect_interactive	セマンティック参照 ID を持つ、すべての対話要素を取得します
get_elements	画面上のすべての要素を一覧表示します
find_element	キーまたはテキストで要素を検索します
wait_for_element	要素が表示されるまで待機します（タイムアウトあり）
get_element_properties	要素の詳細なプロパティを取得します

テキスト操作

ツール	説明
set_text	フィールドのテキストを置き換えます
clear_text	テキストフィールドをクリアします
get_text	テキストの内容を読み取ります

アプリ制御

ツール	説明
get_logs	アプリのログを読み取ります
clear_logs	ログバッファをクリアします

セマンティック参照

inspect_interactive は、安定したセマンティック参照 ID を持つ要素を返します。

button:Login          → Login button
input:Email           → Email text field
toggle:Dark Mode      → Dark mode switch
button:Submit[1]      → Second Submit button (disambiguated)

形式：{role}:{content}[{index}]

7 つのロール：button、input、toggle、slider、select、link、item

UI の変更後も機能する、信頼性の高い要素指定には参照を使用します。

tap(ref: "button:Login")
enter_text(ref: "input:Email", text: "[email protected]")

テストのワークフロー

基本ループ

screenshot() → inspect_interactive() → tap/enter_text → screenshot() → verify

操作の前後には必ず screenshot() を呼び出してください。画面遷移後は wait_for_element() を使用してください。アプリの画面遷移には時間がかかります。

検証チェックポイント

• screenshot() の後：操作を行う前に、想定した画面が表示されていることを確認します。
• tap() または enter_text() の後：screenshot() を呼び出し、UI が応答したことを確認します。
• 画面遷移の後：タイムアウトを設定して wait_for_element(key: "target_screen") を使用します。タイムアウトした場合は、screenshot() と get_logs() を呼び出して原因を調べます。
• 想定外の状態になった場合：get_logs() と inspect_interactive() を呼び出し、どの要素が表示されているかを確認します。

要素の指定優先度

1. ref:（最も信頼性が高い）— inspect_interactive() のセマンティック ref
2. key: — 開発者が設定したウィジェットキー
3. text: — 表示されているテキスト（テキストが変わると不安定です）
4. 座標 — 最終手段です。画面サイズが異なると動作しなくなります

リンク

• GitHub
• npm
• ドキュメント
• pub.dev
• VSCode 拡張機能