patrol-setup

Patrol 设置

先在 Android 模拟器上通过一个 Patrol 测试。请一开始就告知用户，这仅涵盖 Android（pubspec 中的 patrol: 块 + 原生 Android）；iOS 和其他平台遵循相同的安装文档，但不属于本次初始设置。

本技能介绍了有序流程和容易踩坑之处；权威文档是版本、原生配置和代码的准确信息来源——每个步骤都应遵循文档，而不是自行猜测：

• 安装 + 原生设置（依赖项、patrol: 块、Android、iOS、flavor）— https://patrol.leancode.co/documentation
• 编写第一个测试 — https://patrol.leancode.co/documentation/write-your-first-test

1. 配置 Patrol

按照 Setup 步骤操作，并直接链接到相关位置：

• 在 pubspec.yaml 中添加 patrol dev dependency 和 patrol: 块 — https://patrol.leancode.co/documentation#add-patrol-dependency
• 原生 Android（测试运行器、orchestrator、MainActivityTest.java）— https://patrol.leancode.co/documentation#android-setup （Groovy 构建文件：https://patrol.leancode.co/documentation#old-android-setup）
• 如果项目使用 build flavor，请进行相应配置 — https://patrol.leancode.co/documentation#flavors

2. 编写第一个最小化测试

按照 write your first test 中的说明使用当前 API： https://patrol.leancode.co/documentation/write-your-first-test

第一个测试应当独立自包含——仅使用 Flutter 框架组件，不依赖应用或后端——这样测试通过就能证明测试框架本身正常。将其放在 patrol_test/（或配置的 test_directory）中。

3. 忽略 bundle 和机密信息

根据 Setup 部分，将 test_bundle.dart（由 Patrol 生成）和 .patrol.env（你的 dart-defines，通常包含机密信息）添加到 Git 忽略列表： https://patrol.leancode.co/documentation#setup

4. 在模拟器上运行

启动 Android 模拟器，并在运行前等待其完全启动——在启动过程中运行测试会失败。然后使用 patrol test 运行单个测试。测试通过即表示设置完成。

易踩坑之处

• 无法解析 MainActivity（Java） — 将 MainActivityTest.java 中的 package 设置为应用的 applicationId。
• 其他错误（bundle 构建失败、卡住、flavor 不匹配）— 请参阅文档 FAQ：https://patrol.leancode.co/documentation#faq

下一步：Patrol MCP（可选）

设置通过后，告知用户 Patrol MCP 已提供，可按需设置——它能让 AI Agent 运行测试、截取屏幕截图、读取原生 UI 树，并驱动交互式会话。由用户决定；如果用户需要，请按照 README 操作：https://pub.dev/packages/patrol_mcp