flutter-mcp-testing

name	flutter-mcp-testing
description	Flutter 四工具联合测试：Marionette MCP（16 tools）+ Dart MCP（25 tools）+ Mobile MCP（21 tools）+ Codex CLI。 Marionette tap by text、热重载循环、widget tree 检查、录屏、截图存档、多语言测试。 触发关键字：marionette、mcp 测试、热重载、flutter driver、widget tree、录屏、截图对比

核心定位

三个 MCP 工具各管一层，组合覆盖 Flutter 开发全流程：

Dart MCP (25 tools)     — 代码层：分析、热重载、测试、widget 检查、driver 自动化
Mobile MCP (21 tools)   — 设备层：截图、录屏、原生 UI 操作、安装、启动
Codex CLI               — 审查层：只读代码审查、独立安全分析

一、Dart MCP 完整工具清单（25 个）

代码分析（4 个）

工具	用途	参数
analyze_files	静态分析	roots[].root(file URI), roots[].paths[]
hover	光标悬停信息（类型、文档）	uri, line(0-based), column(0-based)
signature_help	函数签名帮助	uri, line, column
resolve_workspace_symbol	模糊搜索符号	query(大小写不敏感)

应用生命周期（5 个）

工具	用途	参数
launch_app	启动 Flutter 应用	root, device, target(默认 lib/main.dart)
list_devices	列出可用设备	无
list_running_apps	列出运行中的应用	无
stop_app	终止应用	pid
get_app_logs	获取日志	pid, maxLines(默认 500, -1=全部)

热更新 + 调试（4 个，需先 connect）

工具	用途	参数
connect_dart_tooling_daemon	连接运行中的应用	uri(DTD URI, 从 launch_app 返回)
hot_reload	热重载（保持状态）	clearRuntimeErrors(bool)
hot_restart	热重启（重置状态，更新 const）	无
get_runtime_errors	获取运行时错误	clearRuntimeErrors(bool)

Widget 检查（4 个，需先 connect）

工具	用途	参数
get_widget_tree	获取 widget 树	summaryOnly(true=仅用户代码 widget)
get_selected_widget	获取选中 widget 详情	无
set_widget_selection_mode	开关 widget 选择模式	enabled(bool)
get_active_location	获取编辑器光标位置	无

Flutter Driver 自动化（1 个工具，多命令）

命令	用途
tap	点击 widget
enter_text	输入文本
get_text	获取 widget 文本
scroll	滚动（dx/dy/duration/frequency）
scrollIntoView	滚动至 widget 可见
send_text_input_action	发送输入法动作（done/go/search/send/next）
set_text_entry_emulation	设置文本输入模拟
waitFor	等待 widget 出现
waitForAbsent	等待 widget 消失
waitForTappable	等待 widget 可点击
get_offset	获取 widget 位置
screenshot	截图
get_health	检查应用健康
get_diagnostics_tree	获取诊断树

Finder 类型：ByType / ByValueKey / ByText / BySemanticsLabel / ByTooltipMessage / PageBack / Descendant / Ancestor

项目创建（1 个，默认禁用）

工具	用途	参数
create_project	创建新 Dart/Flutter 项目	directory, projectType(dart/flutter), root(file URI), template, platform[]

包管理 + 测试（6 个）

工具	用途
pub	add/remove/get/deps/outdated/upgrade
pub_dev_search	搜索 pub.dev（支持 topic: sdk: dependency: 等）
read_package_uris	读取包文件内容
dart_fix	自动修复代码问题
dart_format	格式化代码
run_tests	跑测试（支持 fail-fast/coverage/shard/tags）

---

二、Mobile MCP 完整工具清单（21 个）

设备管理（6 个）

工具	用途
mobile_list_available_devices	列出所有设备/模拟器
mobile_list_apps	列出已安装 app
mobile_launch_app	启动 app（支持 locale 参数）
mobile_terminate_app	关闭 app
mobile_install_app	安装 apk/ipa/app
mobile_uninstall_app	卸载 app

屏幕信息（3 个）

工具	用途	参数
mobile_get_screen_size	屏幕尺寸	device(必填)
mobile_get_orientation	获取横竖屏	device(必填)
mobile_set_orientation	设置横竖屏	device(必填), orientation("portrait"/"landscape")

截图录屏（4 个）

工具	用途
mobile_take_screenshot	截图返回图片（给 LLM 看）
mobile_save_screenshot	截图存文件（saveTo 必须 .png/.jpg）
mobile_start_screen_recording	开始录屏 MP4
mobile_stop_screen_recording	停止录屏，返回文件路径

UI 操作（8 个）

工具	用途
mobile_list_elements_on_screen	获取无障碍树（坐标、标签）
mobile_click_on_screen_at_coordinates	单击
mobile_double_tap_on_screen	双击
mobile_long_press_on_screen_at_coordinates	长按（duration 可设 1-10000ms）
mobile_swipe_on_screen	滑动（方向+距离+起点）
mobile_type_keys	输入文字（submit 可按回车）
mobile_press_button	硬件键（HOME/BACK/VOLUME）
mobile_open_url	打开 URL（需 MOBILEMCP_ALLOW_UNSAFE_URLS=1 才支持 deep link）

---

二点五、Mobile MCP 操作 Flutter 的可靠性规则

来源：2026-04-15 实测，Mobile MCP 坐标点击 Flutter UI 平均 3 次才命中。

Flutter 自己渲染 UI，平台无障碍树只有粗略区域，坐标经常偏。遵循以下规则提升成功率：

规则 1：永远先 list_elements，不要猜坐标

错误：截图 → 目测"大概在这" → click(240, 550)
正确：list_elements_on_screen → 找到元素 → click(x + width/2, y + height/2)

规则 2：文字输入用 adb/xcrun，不用 type_keys

Android: adb -s {device} shell input text "91234567"
iOS sim: xcrun simctl keyboardInput {device_id} 91234567

type_keys 依赖焦点状态，Flutter 经常吃不到。adb input 直接注入到系统层，100% 可靠。

规则 3：等元素出现后再操作

操作前先 take_screenshot 确认页面状态
弹窗/页面切换后等 1-2 秒再 list_elements
不要连续快速操作

规则 4：有 Marionette 就用 Marionette

Marionette MCP 的 tap("文字") 直接在 Flutter 层操作，不走坐标，一次命中。 配好后优先用 Marionette，Mobile MCP 只用于原生弹窗和截图。

配置状态：MCP server marionette_mcp 0.5.0 已全局安装 + 已配在 .claude.json。 App 端 marionette_flutter 主仓库是 0.4.0（不推到 dev），worktree 里需手动升到 ^0.5.0： sed -i '' 's/marionette_flutter: ^0.4.0/marionette_flutter: ^0.5.0/' pubspec.yaml && flutter pub get 不升的话连接会报 version mismatch。每次新 worktree 记得做这步。

Marionette MCP 工具清单（16 个）

工具	用途	参数
connect	连接运行中的 Flutter app	VM service URI (ws://127.0.0.1:xxxxx/ws)
disconnect	断开连接	无
get_interactive_elements	列出屏幕上所有可交互元素	无
tap	点击元素	key 或可见文本
double_tap	双击元素	key 或可见文本
long_press	长按元素	key 或可见文本
enter_text	输入文字	key（匹配目标字段）
scroll_to	滚动到元素可见	key 或可见文本
swipe	滑动	方向 + 距离
pinch_zoom	捏合缩放	缩放比例
press_back_button	按返回键	无
take_screenshots	截图（base64）	无
hot_reload	热重载	无
get_logs	获取日志	需 app 端配 LogCollector
list_custom_extensions	列出自定义 VM extension	无
call_custom_extension	调用自定义 extension	extension 名 + 参数

三、工具选择决策树

需要操作 Flutter widget？
├── Marionette 已连接 → tap("文字") / enter_text（最可靠，一次命中）
├── 知道 widget 类型/Key → flutter_driver ByType/ByValueKey（精确）
├── 只知道屏幕坐标 → Mobile MCP click（先 list_elements 取精确坐标）
└── 原生系统弹窗/权限框 → Mobile MCP（Marionette/flutter_driver 看不到原生 UI）

需要检查 UI 结构？
├── Flutter widget 树 → Dart MCP get_widget_tree
└── 平台无障碍树 → Mobile MCP list_elements_on_screen

需要截图？
├── 给 LLM 看 → Mobile MCP take_screenshot
├── 存文件附 PR → Mobile MCP save_screenshot
└── Flutter 渲染级截图 → flutter_driver screenshot

需要录屏？
└── Mobile MCP start/stop_screen_recording（唯一选择）

---

四、常用工作流

工作流 1：Hot Reload 快速迭代

1. mcp__dart__list_devices()
2. mcp__dart__launch_app(root, device, target)    → 获取 DTD URI
3. mcp__dart__connect_dart_tooling_daemon(uri)
4. 循环：
   a. 编辑代码
   b. mcp__dart__hot_reload(clearRuntimeErrors: true)
   c. mcp__dart__get_runtime_errors()
   d. 有错误 → 修复 → 回到 a
   e. 无错误 → 继续下一个改动
5. 需要更新 const → mcp__dart__hot_restart()

工作流 2：设备全流程测试 + 录屏

1. mcp__mobile-mcp__mobile_start_screen_recording(device)
2. mcp__dart__flutter_driver(command: "tap", finderType: "ByText", text: "登录")
3. mcp__dart__flutter_driver(command: "enter_text", text: "91234567")
4. mcp__dart__flutter_driver(command: "waitFor", finderType: "ByType", type: "OtpPage")
5. mcp__mobile-mcp__mobile_save_screenshot(device, saveTo: "/tmp/login_otp.png")
6. mcp__mobile-mcp__mobile_stop_screen_recording(device) → MP4 文件

工作流 3：Widget 调试

1. mcp__dart__get_widget_tree(summaryOnly: true)  → 确认结构
2. mcp__dart__get_runtime_errors()                  → 找 overflow 等
3. 有问题时：
   mcp__dart__set_widget_selection_mode(enabled: true)
   → 在设备上点选有问题的 widget
   mcp__dart__get_selected_widget()                → 获取 constraints/size/render 详情
   mcp__dart__set_widget_selection_mode(enabled: false)

工作流 4：Codex 只读审查

codex exec \
  -s read-only \
  -c 'mcp_servers={}' \
  --ephemeral \
  -C <worktree路径> \
  "Review git diff dev..HEAD. Flutter MVVM + Riverpod.
   Focus: architecture, logic bugs, security, dead code.
   Output: Critical/High/Medium/Low with file:line."

注意：

• -C 必须指向 worktree 路径，不能用主仓库路径（否则读错分支代码）
• -c 'mcp_servers={}' 禁用所有 MCP（避免 Figma 卡死）

---

四点五、Golden Test 互补（CI 自动回归）

四工具（Marionette + Dart MCP + Mobile MCP + Codex）覆盖开发阶段的实时验证，Golden Test 覆盖 CI 阶段的自动回归：

层级	工具	触发时机
开发实时	Marionette tap + Dart MCP widget tree + Mobile MCP 截图	每次 hot_reload 后
CI 回归	Golden Test（alchemist / golden_test）	每次 PR push
Figma 对比	ImageMagick SSIM（verify-ui-auto skill）	UI 功能完成时

推荐包：

• alchemist 0.14.0 — 双 golden 系统（CI golden 跨平台一致 + 平台 golden 人可读），成熟稳定，默认推荐
• golden_test 1.0.1 — 轻量级，内建多设备 + 多语言 + 容差，适合新项目尝鲜
• golden_toolkit 0.15.0 — 已标记 discontinued，存量项目可继续用，不建议新接入

跨平台要点：

• Widget golden test 跑在 Flutter test harness（无头渲染），不是模拟器/真机
• macOS vs Linux 渲染差异（字体引擎、阴影、文字抗锯齿等）→ 用 Alchemist 双 golden 或 macOS CI runner
• Flutter 版本升级（尤其 3.27+ Impeller 默认化）后 golden 可能需要更新
• 容差推荐：0.0002（= 0.02%，M1 vs x86），>0.01（>1%）太高会漏 bug

详见 skill: verify-ui-auto

---

五、Flutter 特别注意

1. flutter_driver 命令需要 enableFlutterDriverExtension() — tap/screenshot/waitFor 等命令需要 app 端调用此函数。当前项目未启用，因此日常开发中 flutter_driver UI 操作不可用。仅 get_widget_tree（87KB，iOS 模拟器实测）和 get_runtime_errors 等诊断工具可通过 DTD 连接直接使用，不需要 extension。
2. Flutter widget 不自动出现在平台无障碍树 — Material 组件（TextField/Button 等）自带 Semantics，自定义 widget 需手动加 Semantics wrapper
3. flutter_driver vs Mobile MCP：
   • flutter_driver 通过 VM Service 直接操作 Flutter widget，精确但只能操作 Flutter UI
   • Mobile MCP 通过平台 accessibility API 操作，能操作原生 UI 但看不到无 Semantics 的 Flutter widget
4. Dart MCP 需要 Dart SDK >= 3.9，启动命令：dart mcp-server --force-roots-fallback

---

六、环境变量

变量	作用
MOBILEMCP_ALLOW_UNSAFE_URLS=1	允许 deep link scheme（myapp://）
MOBILEMCP_DISABLE_TELEMETRY=1	禁用匿名遥测
MOBILEFLEET_ENABLE=1	启用远程设备池

七、dev-team Phase 对应

Phase	Marionette MCP	Dart MCP	Mobile MCP	Codex
1 探索	—	analyze_files, resolve_workspace_symbol, hover	—	—
2 编码	—	hot_reload 循环, run_tests, dart_format	—	—
3 集成	—	run_tests(fail-fast), analyze_files	save_screenshot 对比	—
4 真机	tap/enter_text（首选）	flutter_driver, get_widget_tree, get_runtime_errors	录屏, save_screenshot, launch_app(locale)	—
4.8 回归	—	— (Golden Test via flutter test)	—	—
5 审查	—	—	—	exec read-only
6 监控	—	—	—	exec review

Related skills

• flutter-device-crud-testing — use as a higher-level workflow that orchestrates flutter-mcp-testing for systematic screen-by-screen validation.
• flutter-verify — use after flutter-mcp-testing to confirm all integrations and regressions are resolved.