Patrol 测试架构是 LeanCode 团队在其 Patrol 项目中推荐的一套端到端测试编写规范，用于以模块化方式组织 Patrol E2E 测试代码。
【用途】 该架构用于指导开发者如何结构化 Patrol 测试，使测试可复用、可读且易于维护，同时配套 Patrol MCP 工具执行与调试测试。适用场景为使用 Patrol 编写 Flutter 应用的端到端测试。
【主要能力】
- 结构模式：使用自定义 testApp 包装器承载所有测试；每个测试文件只包含一个测试；通过 Modules（按用户视角划分的功能模块，如 Auth、Home、Downloads、Player）、System（原生交互类，使用 $.platform 完成不属于被测应用的操作，如开启飞行模式）和 ApiClients（聚合与测试后端、测试邮箱或第三方服务通信的客户端）组织代码。
- 模块方法组织：不写注释而使用描述性命名；过长方法可按逻辑步骤拆分；对多处复用的步骤序列（如长引导流程）提供包装方法调用私有方法。
- Patrol MCP 工具：patrol-run 运行测试并等待完成，patrol-screenshot 按平台截图调试，patrol-quit 优雅退出会话，patrol-status 查看状态与近期输出，patrol-native-tree 获取原生 UI 树用于编写原生交互。
- 测试键（test keys）：为涉及测试的控件分配键，按功能目录建立 keys.dart，主 keys.dart 仅聚合并导入各功能键，键值唯一、按字母排序，区分固定键与参数化键，使用 enums 或 DTO 作为参数。
【使用方式】 编写新测试时按顺序进行：直接打开关键文件（模块聚合器、测试包装器、主 keys.dart 及对应功能文件）；检查现有模块中可复用的函数；为所需控件分配测试键；开始写测试，复用现有模块并放入新测试文件，Patrol 动作直接写在测试文件中而非在模块内新建方法；开发过程中频繁运行测试，每完成一组逻辑步骤即运行以尽早发现问题；测试通过后把新代码重组进现有或新建模块，测试文件只能调用模块方法，不得直接使用 Patrol API；重组后再次运行确认通过。使用 Patrol MCP 的 patrol-run 运行单个测试文件，patrol-screenshot 截图，patrol-quit 退出，patrol-status 查看状态，patrol-native-tree 获取原生树。
【关键规则】 直接使用 Patrol API 的文件必须导入 package:patrol/patrol.dart；实现动作前始终先查看 Patrol API 与 $.platform 方法；不使用 flutter_test 包；只用 Patrol MCP 运行单个测试、用 patrol test 运行所有测试，绝不使用 flutter test；不自行编写 patrolSetUp 和 patrolTearDown；在 tap、scrollTo、enterText 前后不写等待方法（Patrol 自动处理），仅在测试末尾使用；仅用键查找控件；避免不必要的 try-catch；不在动作后写断言，只在测试末尾断言，优先用 waitUntilVisible；及时处理原生对话框，原生权限优先使用 $.platform.mobile.grantPermissionWhenInUse；只给参与测试的控件分配键，只给已有控件添加 key 参数，不修改控件签名、不重构现有结构、不硬编码键、不新建控件，键必须来自 keys.dart，且每个键都要分配给控件。
【限制】 该架构面向 Patrol 与 Flutter 生态，需配合 Patrol MCP 服务器使用；文档未提供定价、平台支持范围、性能效果等信息。文档中部分示例代码含占位实现（如 System 类中的注释实现），实际实现需开发者自行完成。
【分类】 依据其主要用途为编写与组织 E2E 测试，归类为 testing（测试与质量）。