はじめに
こんにちは、リテールハブ開発部の杉森です。
近年、Playwright MCPを使ってブラウザ操作やテストを自然言語経由で実施している事例が多数見られるようになりました。その流れを見ていて、「これをFlutterアプリでも実現できないか？」と考えるようになりました。
調査を進める中で、Maestro MCPという選択肢があることを知り、実際にFlutterアプリのE2Eテストを試してみました。本記事では、その取り組みについて紹介します。
Maestroとは
Maestro（マエストロ）は、モバイルアプリケーション向けのE2Eテスト自動化フレームワークです。iOS、Android、React Native、Flutterなど、幅広いプラットフォームに対応しています。
主な特徴：
- シンプルなYAML記法でテストシナリオを記述
- クロスプラットフォーム対応（iOS/Android両方で同じテストを実行可能）
- 直感的なコマンドでタップ、スワイプ、入力などの操作を記述
Maestroは、複雑なセットアップを必要とせず、短期間でE2Eテストを構築できることが大きな魅力です。
参考リンク
Maestro公式サイト
Maestro GitHub
Maestro MCPとは
Maestro MCPは、Model Context Protocol（MCP）に対応したMaestroのサーバー実装です。MCPは、AIモデルとツールを接続するための標準プロトコルで、Claude Codeなどのツールから自然言語でMaestroの機能を呼び出せるようになります。
従来は、Maestro YAMLファイルを手動で記述してテストを実行する必要がありましたが、Maestro MCPを使うことで、自然言語でテストシナリオを記述するだけで、AIエージェントが適切にテストを実行してくれます。
(備考)Maestro MCPで利用可能なTools
以下は、2025年11月10日時点でMaestro MCPで利用可能なToolsです。
| カテゴリ | ツール | 説明 |
|---|---|---|
| デバイス管理 | list_devices |
接続可能なシミュレータ/エミュレータの一覧を取得する |
start_device |
指定したデバイスを起動する | |
| アプリ操作 | launch_app |
指定したバンドルID/パッケージ名のアプリを起動する |
stop_app |
実行中のアプリを停止する | |
| UI操作 | tap_on |
テキスト、ID、座標などで指定した画面要素をタップする |
input_text |
フォーカスされたテキストフィールドに文字列を入力する | |
back |
デバイスの戻るボタンを押す（Androidのみ有効） | |
| 情報取得 | take_screenshot |
現在の画面をPNG画像として取得する |
inspect_view_hierarchy |
画面のUI階層を取得する | |
| テスト実行 | run_flow |
Maestro YAMLフローをインラインで記述して実行する |
run_flow_files |
既存のMaestro YAMLファイルを読み込んで実行する | |
check_flow_syntax |
Maestro YAMLフローの構文が正しいかを検証する | |
| ドキュメント | cheat_sheet |
Maestroの基本コマンドと構文例を含むチートシートを取得する |
query_docs |
Maestro公式ドキュメントに質問を投げて関連情報を取得する |
インストール方法
Maestro MCPを使用するには、以下の準備が必要です。
1. Maestroのインストール
Maestroをシステムにインストールします。
# Java 17以降が必要です（インストールされていない場合は別途インストールしてください） java -version # Homebrewを使用する場合（macOS） brew tap mobile-dev-inc/tap brew install mobile-dev-inc/tap/maestro # Curlを使用する場合（Linux/macOS） curl -Ls "https://get.maestro.mobile.dev" | bash
参考リンク
Maestro公式ドキュメント - Installing Maestro
2. Maestro MCPの設定
Claude Codeの設定ファイルにMaestro MCPサーバーの設定を追加します。
{ "mcpServers": { "maestro": { "command": "maestro", "args": ["mcp"] } } }
設定後、Claude Codeを再起動することで、Maestro MCPが利用可能になります。
参考リンク
Maestro公式ドキュメント - Installing Maestro MCP
検証
テスト対象アプリの概要
今回は、手動でテストを実施していたFlutterアプリに対して、Maestro MCPを使った自動テストをiOSシミュレータを利用して試してみました。
検証したテストの一例
既存のテスト内容
・アプリを起動(初期化状態)
・オンボーディングの実施
・ホーム画面の表示
・ボトムナビゲーションから「設定ボタン」を押下
・「お気に入り店舗ボタン」を押下
(省略)
・各画面で設定されている店舗情報が反映されているかを確認する
指示内容
MCPを利用してテストを実施するために下記プロンプトを作成しました。
[テスト内容] ・アプリを起動(初期化状態) ・オンボーディングの実施 ・ホーム画面の表示 ・ボトムナビゲーションから「設定ボタン」を押下 ・「お気に入り店舗ボタン」を押下 (省略) ・各画面で設定されている店舗情報が反映されているかを確認する [環境情報] appId: xxxxxxxxxxxx [前提条件] アプリを初期状態（キャッシュクリア）から起動 [確認したいこと] ・各画面で設定されている店舗情報が反映されているかを確認する [スクリーンショット] 各画面のスクリーンショットを/xxxxx/yyyy-mm-dd_hhmmss/*に保存してください。 [注意事項] 必ず、maestro-mcp-testing-guide.md を参照してからテストを行ってください。
※ maestro-mcp-testing-guide.mdは、テスト実施時のノウハウやエラー対処法を蓄積した学習ガイドファイルです。詳細は後述の「3. 実行時のエラーと学習プロセスの整備」で説明します。
結果
- 手動で実施していたテスト内容を自然言語ベースの指示だけで実施・確認できた
- 証跡として各画面のスクリーンショットを取得できた
困った点と対応内容
想定通りテストを実施することができたのですが、Maestro MCPを使う上で、何点か詰まる箇所がありました。以下、遭遇した問題と対応策を紹介します。
1. 一部のMCP Toolが利用できない
問題
Maestroに関する情報を取得する際に利用される、cheat_sheetとquery_docsを実行した際に下記エラーが発生してしまいました。
Error: MAESTRO_CLOUD_API_KEY environment variable is required
対応策
Maestro Studio Desktopをインストールすると、APIキーの指定なしで利用できるようです。
参考リンク
Maestro公式ドキュメント - Maestro Studio Desktop
2. tap_onで押下できないウィジェットがある
問題
特定のボタン押下ができず、run_flowを利用した座標ベースのボタン押下処理を実施するケースが発生していました。
対応策
Maestro MCPに限らず、一般的なE2Eテストでも同様ですが、ウィジェットを識別しやすい状態にしておかないと、ボタンを押下する際に、座標情報でボタン押下等を実施する必要が出てきます。
FlutterのSemanticsウィジェットを活用し、各UI要素に適切なラベルや識別子を付与することが重要です。
例）
Semantics( label: 'ログインボタン', button: true, child: ElevatedButton( onPressed: _handleLogin, child: Text('ログイン'), ), )
参考リンク
Maestro公式ドキュメント - Flutter Support
3. 利用可能な操作が限定的
問題
Maestro MCPで直接実行できる操作には制限があり、以下の操作で困ることがありました：
- スクリーンショットの保存先指定：
take_screenshotコマンドでは、指定したフォルダに保存することができない - 画面録画：Maestro MCPには画面録画機能がない
- スワイプ操作：Toolsだけだと、tap_onやinput_textなどの最低限の操作しか実施できない。
対応策
これらの制約に対して、以下のアプローチを取りました：
スクリーンショット保存の場合
xcrun simctlを使用して、スクリーンショットを指定したパスに保存できるようにしました。
例)
# iOSシミュレータのスクリーンショットを指定パスに保存 xcrun simctl io <device_id> screenshot /xxxxx/yyyy-mm-dd_hhmmss/screenshot.png
画面録画の場合
同様にxcrun simctlを使用して、画面を録画することができました。
ですが、Claude Code Sonnet 4.5でテストを実行した場合、AIエージェントの処理時間が含まれるため、録画時間がどうしても長くなってしまいます。そのため、個人的にはあまり実用的ではないと感じております。
例)
# 録画を開始（バックグラウンド実行） xcrun simctl io <device_id> recordVideo xxxxx/yyyy-mm-dd_hhmmss/xxxxx.mov & # 操作を実行... # 録画を正常終了(バックグラウンド処理の停止)
スワイプ操作の場合
run_flowコマンドを使用して、Maestro YAMLを直接記述するように指示をして対応しました。
例)
- swipe: direction: UP duration: 500
4. 実行時のエラーと学習プロセスの整備
問題
実行時には、スムーズにテストが実施されないことが何点かありました：
run_flow内のコマンドのsyntaxエラー- 画面要素の識別ミス
- 適切に動作しないmaestroコードの生成
これらの問題はAIエージェントが自律的に解決をしてくれるのですが、再度別プロセスでテストを実施した際に同じミスを繰り返すケースが見受けられました。
対応策
テスト実施時に詰まった内容と解決方法をmaestro-mcp-testing-guide.mdに適宜蓄積していくアプローチを取りました。テスト実行時に作成したmdファイルを参照してもらうことで、同じエラーを繰り返さないようにしています。
以下のような情報を蓄積しています：
- よくあるミスと対処法
- 各画面での要素の識別方法
- テストパターンのサンプル
- 参考するべきMaestro関連のリンク集
今後の展望
今回はテストケースをこちらから提供する形でしたが、今後は以下のような取り組みにも挑戦したいと考えています：
- テスト設計からの自動化：機能仕様から自動的にテストケースを生成
- 探索的テストの実施：AIに自由にアプリを操作させ、潜在的なバグを発見
- 回帰テストの整備：既存機能の動作を継続的に確認する自動テストスイートの構築
これらの取り組みは、今回のようにテストケースを事前に提供する形よりも、より効果的なテスト自動化を実現できる可能性があると考えています。
まとめ
Maestro MCPを使ったFlutterアプリのE2Eテスト自動化について紹介しました。
モバイルアプリの自動テストに興味がある方は、ぜひMaestro MCPを試してみてください！
