用途：在 Flutter 项目中运行与管理 Patrol 集成测试（E2E），支持 macOS、iOS、Android 和 Chrome 四个平台，适用于编写、执行和调试 Patrol 测试用例。
主要能力：通过 patrol CLI 运行指定或全部集成测试，使用 --device 指定设备避免交互式选择，使用 --target 指定测试文件或目录，并通过 --dart-define 传入 SOLIPLEX_BACKEND_URL。各平台示例：macOS 使用 --device macos；iOS 使用模拟器设备 ID，必要时用 --ios=18.6 指定系统版本，可用 xcrun simctl list devices booted 查找设备；Android 使用 adb devices 的序列号，模拟器访问宿主机 localhost 需用 10.0.2.2；Chrome 需要 Node.js >= 18，支持 --web-headless true 无头运行及 --web-viewport 自定义视口。ARGUMENTS 为空或 all 时运行 integration_test/ 全部测试，为文件名时运行该文件。
使用方式与测试模式：运行前确认后端以 --no-auth-mode 启动、patrol --version 可用、dart analyze integration_test/ 通过、test_bundle.dart 为最新（缺失时可删除让其重新生成）。测试中避免 pumpAndSettle，改用 waitForCondition、harness.waitForLog 或 tester.pump(duration)。标准结构包含 verifyBackendOrFail、ignoreKeyboardAssertions、TestLogHarness 初始化、pumpTestApp 及 finally 中 dispose。查找组件可用 find.byType 等，文本输入避免 find.bySemanticsLabel，改用 find.byType(TextField)。
调试采用两阶段流程：阶段一用 dart MCP 工具（launch_app、get_widget_tree、get_app_logs、get_runtime_errors）发现查找器与日志模式；阶段二在 patrol run 中用 TestLogHarness 做进程内断言，因为 xcodebuild 启动不暴露 DTD URI。
限制与注意事项：该仓库为 git worktree，pre-commit 钩子调用 flutter/dart 前需 unset GIT_DIR，否则版本显示 0.0.0-unknown，可用 scripts/ 下的包装脚本处理。常见问题包括缺少 --device 导致多设备提示、PAT H 未包含 ~/.pub-cache/bin、macOS 缺少 entitlement 导致等待挂起、enterText 匹配到 Semantics 报错、iOS OS 版本不匹配、Android 连接宿主 localhost 被拒、Chrome 缺少 playwright 或 CORS 错误等。首次配置需参考各平台 setup 指南。