测试移动开发开发工具CLI【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址https://gitcode.com/GitHub_Trending/ma/Maestro点击查看免费下载本文以 Maestro 开源仓库中e2e/demo_app/CLAUDE.md为骨架完整讲解这个 Flutter 测试目标应用demo_app的定位、构建方式、lib/测试屏幕架构、.maestro/Flow 组织规范以及编写权限相关 Flow 时最容易踩的坑。读完本文你将掌握如何为 Maestro 框架的某项能力构造可观察的测试场景、如何组织跨平台 Flow 并利用config.yaml控制执行范围以及如何在新增测试屏幕时遵循仓库约定。demo_app 是什么为 Maestro 而生的 E2E 测试目标demo_appe2e/demo_app/是一个基于 Flutter 构建的跨平台Android 与 iOS示例应用其唯一职责是充当 Maestro 移动端 UI 自动化测试框架的目标应用。正如 CLAUDE.md 开头所强调的它不是生产应用——它的每一个屏幕都是为了锻炼 Maestro 的某项具体功能、或复现某个已报告的 Bug 而存在。这带来两个重要推论贯穿整个仓库的设计屏幕只是载体Flow 才是主体。新增测试屏幕的目的不是测试这个屏幕本身而是让某个 Maestro 行为变得可观察、可断言当需要验证新的 Maestro 功能时新屏幕/新行为会持续被添加到这里。因此这个应用实际上是一份Maestro 能力矩阵的活文档与 lib/ 下的屏幕一一对应。应用的分发方式见 e2e/demo_app/README.md应用二进制被构建后上传到存储桶链接记录在 e2e/manifest.txtMaestro 的 E2E 流水线运行时下载这些二进制并执行 .maestro/ 中的 Flow连同其他目标应用一起。构建与运行四个核心 Flutter 命令对 demo_app 的常规开发操作全部走 Flutter CLI命令如下摘自 CLAUDE.md# 运行应用需要已连接的设备或模拟器 flutter run # 构建 Android APK flutter build apk # 构建 iOS 模拟器应用 flutter build ios --simulator # 静态分析代码 flutter analyze其中flutter build ios --simulator用于产出 iOS 模拟器可安装的 Runner.app是本地 E2E 调试最常用的一条flutter build apk对应 Android 侧产物。flutter analyze配合 analysis_options.yaml仓库使用 flutter_lints 规则集见 pubspec.yaml做代码质量把关。该应用的依赖列表见 pubspec.yaml本身就是测试点清单webview_flutterWebView 测试、permission_handler权限测试、sensors_plus传感器测试、geolocator定位测试、connectivity_plus网络连接测试、flutter_launch_arguments启动参数注入、app_linksDeep Link 测试、shared_preferences状态持久化测试等。应用架构lib/测试屏幕与启动参数注入屏幕即场景一张表看懂 lib/main.dart 是应用首页用一个GridView.count3 列铺满各测试入口按钮每个按钮Navigator.push到对应的独立测试屏幕。每个屏幕是一个独立 Dart 文件、对应一个特定测试场景CLAUDE.md 给出了完整的映射表文件用途form_screen.dart带邮箱/密码校验的登录表单input_screen.dart键盘与文本输入行为swiping_screen.dart滑动手势测试nesting_screen.dart深层嵌套的 Widget 层级location_screen.dart通过geolocator获取 GPS 定位流式推送位置更新sensors_screen.dart设备传感器仅 Androidwebview.dart通过webview_flutter嵌入 WebViewdefects_screen.dart故意制造的 UI 怪癖用于缺陷回归cropped_screenshot_screen.dart截图裁剪的边界情况notifications_permission_screen.dart通知权限请求流程permission_check_screen.dart被动展示权限状态location、all-files通过permission_handler读取绝不调用requestPermission()从而确定性地反映预先授予的状态issue_1619_repro.dart、issue_1677_repro.dart具体 Bug 的复现用例此外从 lib/ 目录可以看到比文档更全的屏幕集合包括animation_screen.dart、carousel_screen.dart、connectivity_screen.dart、gesture_tester_screen.dart、orientation_screen.dart、patient_care_screen.dart、scrollable_list_screen.dart、webview_deep_dom_test_screen.dart、webview_devtools_test_screen.dart等分别覆盖动画、轮播、网络切换、手势、横竖屏、assertScreenshot阈值、长列表滚动、WebView 深层 DOM、WebView DevTools 等场景并全部在 main.dart 中注册了入口按钮。几个值得注意的平台条件渲染见 main.dartSensors入口仅在!kIsWeb时渲染传感器场景面向 Android/iOS 真机Health Access入口仅在 iOS 上渲染通过MethodChannel(com.example.demo_app/health_access)调用原生层对应 iOS 工程中的 HealthAccessManager.swiftPassword autofill Test通过MethodChannel(com.example.demo_app/password_test)打开原生密码自动填充页面对应 PasswordTestViewController.swiftissue 1619/1677 repro、Webview系列、Cropped Screenshot、Notifications Permission、Permission Check等均以独立按钮暴露。启动参数注入Maestro 在启动时配置应用状态demo_app 通过flutter_launch_arguments插件读取启动参数使得Maestro Flow 可以在launchApp时配置应用初始状态。在 main.dart 中final counterValue await _flutterLaunchArgumentsPlugin.getInt(initialCounter); final delayValue await _flutterLaunchArgumentsPlugin.getInt(delay); setState(() { _counter counterValue ?? 0; _delay delayValue ?? 0; });即支持initialCounter初始计数值与delay点击加一按钮时的模拟延迟秒数两个参数。delay的典型用途是制造点击后界面延迟变化的时序窗口用于测试 Maestro 的waitForAnimationToEnd等同步机制对应 .maestro/commands/waitForAnimationToEnd.yaml。顺带一提应用还内置了 Deep Link 处理example://form会直接导航到表单页main.dart对应 Android 侧AndroidManifest.xml中注册的examplescheme intent-filter 与https://maestro.mobile.dev的 App Links 声明。Maestro Flow.maestro/目录的组织规范目录结构CLAUDE.md 给出了.maestro/下各子目录的语义根目录*.yaml主要的通过/失败测试用例打passing标签或用断言预期失败commands/可复用的 Maestro 命令定义如assertVisible.yaml、inputText.yamlandroid_device_configuration/与ios_device_configuration/测试前运行的设备设置 Flow关闭自动纠错、设置时区、启用传感器等issues/专门复现已报告 Maestro Bug 的 Flowexperimental/不稳定/进行中的 Flow不纳入 CIscripts/被evalScript命令使用的 JavaScript 辅助脚本。实际仓库目录与此完全吻合commands/下已积累 50 个命令定义文件assertVisible.yaml、inputText.yaml、scrollUntilVisible.yaml、setLocation.yaml、takeScreenshot.yaml、assertScreenshotCropped.yaml、retry.yaml等issues/下存放issue1777.yaml、issue1677.yaml、issue565_form.yaml、maestro_issue_1619/等复现用例。config.yaml控制 Flow 收录范围.maestro/config.yaml 决定了执行maestro test .maestro/时包含哪些 Flow 目录flows: - * - ios_device_configuration/* - android_device_configuration/* - commands/*注意config.yaml并没有显式列出issues/与experimental/——experimental/不纳入 CI 正是靠这个配置实现的其存在本身即被配置排除。Flow 运行命令CLAUDE.md 给出的三条核心命令适用于脚本化或 CI 运行场景# 运行全部 Flow maestro test .maestro/ # 运行单个 Flow maestro test .maestro/fill_form.yaml # 按标签运行 maestro test --include-tags passing .maestro/--include-tags passing会筛选出所有打了passing标签的用例这是 CI 中只跑通过用例的惯用法。仓库根目录的 e2e/run_tests、e2e/list_workspaces 等脚本展示了这套 Flow 在更上层 E2E 流水线中的编排方式。一个典型的端到端 Flow 示例是 .maestro/fill_form.yaml它完整覆盖启动清状态 → 导航 → 输入 → 断言的标准链路appId: com.example.example tags: - passing --- - launchApp: clearState: true - tapOn: Form Test - tapOn: Email - inputText: correctmobile.dev - tapOn: Password - inputText: maestro - tapOn: text: Login index: 1 - assertVisible: text: Credentials are correct optional: true # Fix me this part is flaky on CI only not local, needs to be addressed why而 .maestro/commands/assertVisible.yaml 则演示了命令定义文件的双重价值既是命令文档展示assertVisible支持字符串简写、text:与id:三种形态其中id: fabAddIcon对应 main.dart 中通过Semantics(identifier:)暴露的语义标识符又是可直接运行的测试。平台定向Platform targeting一条 Flow 跑双端CLAUDE.md 明确了 Flow 的跨平台编写原则这是本仓库最重要的 Flow 约定默认 Flow同时运行于 Android 与 iOS只有行为确实平台相关时才加android或ios标签优先维护单一跨平台 Flow而不是拆成两个平台文件用${maestro.platform android ? ... : ...}表达式给平台相关值做三元插值用runFlow的when: platform:守卫平台专属步骤。落地示例一.maestro/permission_interpolation.yaml 在env中定义平台化权限值env: ALLOW_VALUE: ${maestro.platform android ? allow : always} DENY_VALUE: ${maestro.platform android ? deny : never}落地示例二.maestro/relatives.yaml 同时展示平台标签与相对定位断言containsChild、leftOf、rightOf、below、above在嵌套层级上的用法并注明android标签的理由是 iOS 使用不同的层级结构。落地示例三.maestro/environment-variables.yaml 展示环境变量参与断言assertTrue: ${MAESTRO_EXAMPLE test-value}依赖运行时注入的MAESTRO_EXAMPLE环境变量。设备配置 Flow测试前的环境准备android_device_configuration/与ios_device_configuration/下的 Flow 在正式用例之前执行负责把设备环境驯服到确定状态。例如 .maestro/android_device_configuration/enable_sensors.yaml 会依次断言加速度计、陀螺仪、罗盘、磁力计、气压计、光传感器、接近传感器、GPS 全部Availableios_device_configuration/disable_autocorrect.yaml 关闭 iOS 自动纠错避免输入文本被系统纠正导致断言失败。App ID所有 Flow 的目标应用统一为appId: com.example.example对应 Android 工程 MainActivity.kt 与 iOS Runner 的 bundle 配置。在launchApp之前应用需要先安装到设备/模拟器上本地用flutter run或flutter build 安装命令完成。权限测试陷阱本仓库最精华的实战经验CLAUDE.md 用一整节专门总结编写权限 Flow 时非显而易见的坑这些经验全部来自真实的跨平台 CI 实践逐条展开如下。陷阱一iOS 侧每个权限都必须在 Podfile 里编译进来permission_handler在 iOS 上的行为是某个权限的 handler 只有在GCC_PREPROCESSOR_DEFINITIONS中设置了对应宏时才会被编译进产物例如PERMISSION_LOCATION1。如果没设宏该权限的.status在 iOS 上会静默返回 denied——无论系统真实授权状态如何。当前 ios/Podfile 通过post_install钩子启用的宏post_install do |installer| installer.pods_project.targets.each do |target| flutter_additional_ios_build_settings(target) target.build_configurations.each do |config| config.build_settings[GCC_PREPROCESSOR_DEFINITIONS] || [ $(inherited), PERMISSION_NOTIFICATIONS1, PERMISSION_LOCATION1, ] end end end即当前仅启用了notifications与location两个权限。修改 Podfile 后必须执行pod install在ios/目录下再flutter build ios——仅仅编辑 Podfile 不会触发重新安装。陷阱二Android 侧运行时权限必须在 Manifest 里声明Android 的运行时权限若未在AndroidManifest.xml中声明就无法被授予pm grant会直接报错。当前 android/app/src/main/AndroidManifest.xml 声明了INTERNET、ACCESS_FINE_LOCATION、ACCESS_COARSE_LOCATION、MANAGE_EXTERNAL_STORAGE。因此例如POST_NOTIFICATIONS目前无法在此应用上被授予——这正是notifications_permission_screen.dart与launchApp通知权限测试的设计约束。陷阱三权限值是平台相关的且校验行为不对称Android 使用allow/deny/unsetiOS 的location使用always/inuse/never/unsetiOS 会校验 location 的值并对其他值抛异常Android 对未知/空值则静默回退为 revoke不报错。跨平台 Flow 必须按平台取值典型写法出自 .maestro/permission_interpolation.yaml- launchApp: clearState: true permissions: location: ${ALLOW_VALUE} # android - allowios - always - tapOn: Permission Check - assertVisible: Location: Allowed该 Flow 的完整逻辑验证了 issue 2416launchApp权限值必须支持变量插值allow → Location: Alloweddeny → Location: Not allowed并且仅 Android用runFlow when: platform: Android守卫未知值/空值回退 revoke的用例iOS 会抛异常所以必须隔离。陷阱四launchApp不带permissions:块时默认all: allow这是本仓库反复依赖的默认行为省略permissions:时Maestro 会默认授予全部权限。因此在大多数非权限用例中无需显式声明权限而权限用例则必须显式给出permissions:块来控制授予/撤销。陷阱五观察权限要被动不要用会弹窗的屏幕这是最容易踩中的坑涉及两个屏幕的取舍permission_check_screen.dart 是一个被动观察器它只通过permission_handler读取Permission.location.isGranted/Permission.manageExternalStorage.isGranted并展示 Allowed / Not allowed从不调用requestPermission()所以不会弹系统对话框能确定性地反映先前launchApp { permissions: }/setPermissions留下的状态是权限断言的首选location_screen.dart 则主动调用Geolocator.requestPermission()见_startLocationUpdates中permission LocationPermission.denied分支会弹出系统权限对话框Android 不会自动关闭并异步解析定位结果——与测试流程产生竞态不适合用来断言权限授予结果。结论断言预先授予的状态用permission_check_screen.dart要测试请求权限的交互流程才用notifications_permission_screen.dart等主动请求场景。陷阱六MANAGE_EXTERNAL_STORAGE是 appOps 权限Android 的MANAGE_EXTERNAL_STORAGE属于appOps 特殊路径权限不是标准的pm grant运行时权限——它无法像普通权限那样用pm grant授予。这一点直接影响了launchApp权限块和setPermissions在此权限上的处理方式编写涉及所有文件访问的权限用例时必须注意。用 MCP 编写与调试 FlowCLAUDE.md 特别推荐编写、运行、调试 Flow 时优先使用 Maestro MCP工作流为list_devices→inspect_screen/take_screenshot→run因为 MCP 会直接返回视图层级与截图比解析 CLI 输出迭代效率高得多CLI 则用于脚本化/CI 场景或无 MCP 可用时。一个关键认知也是新手最容易困惑的点MCP 运行的是已构建的 Maestro而不是你的工作树。如果你修改了e2e/之外的 Maestro 框架代码并想通过 MCP 在本应用上验证重新构建 Maestro重连 MCP例如/mcp reconnect maestro再重新运行 Flow。这与重新构建 demo_app 本身是两回事——demo_app 的 Dart/iOS/Android 改动需要先重建并重装到设备上MCP 才会看到新行为。仓库中 e2e/cli/test-cli.sh 等脚本展示了 CLI 路径的验证方式。新增测试屏幕的标准流程当需要为某个 Maestro 特性新增测试场景时CLAUDE.md 给出了四步规范这也是向该仓库贡献测试的完整路径在lib/下新建feature_screen.dart实现一个StatefulWidget在 lib/main.dart 中为该屏幕添加导航按钮编写锻炼目标 Maestro 特性的 Flow打上[passing]标签——再次强调Flow 才是重点屏幕只是让该 Maestro 行为可观察的载体行为平台相关时才加平台标签见上文平台定向若涉及定位或传感器测试确保平台专属子目录中存在相应的设备配置 Flow如 android_device_configuration/enable_sensors.yaml。小结demo_app 是理解 Maestro E2E 测试方法论的最佳入口它把被测应用抽象成一张张可观察的测试屏幕用 Flow 组织成跨平台的能力验证矩阵并用config.yaml、平台标签、${maestro.platform}插值与runFlow when:守卫解决双端差异权限测试一节则浓缩了permission_handler在 iOS/Android 上最真实的行为差异。读者可以直接在 e2e/demo_app/.maestro/ 与 e2e/demo_app/lib/ 之间对照阅读把本文中的每一条约定映射到实际代码上。赞分享测试移动开发开发工具CLI【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址https://gitcode.com/GitHub_Trending/ma/Maestro点击查看免费下载相关推荐SuperPlane E2E 测试实战指南用 Go 与 Playwright 编写可读、稳定的端到端测试SuperPlane E2E 测试实战指南用 Go 与 Playwright 编写可读、稳定的端到端测试 SuperPlane 的端到端E2E测试用 GoNativeScript 应用 UI 端到端测试实战指南Appium e2e 测试的执行、调试与用例编写NativeScript 应用 UI 端到端测试实战指南Appium e2e 测试的执行、调试与用例编写 本篇指南以 NativeScript 官方仓库中承载Mesop 应用测试指南用 Playwright 编写端到端测试的完整实践Mesop 应用测试指南用 Playwright 编写端到端测试的完整实践 导读 Mesop 是一个用 Python 快速构建 AI 应用的全栈 UI 框架前端后端Web框架上一篇Flue 集成 Jetty 分级评测用 Trajectory 标签跨版本对比 Agent 输出质量下一篇memory-scan未来展望内存管理技术的10大创新方向创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考