用途:指导仓库用户在包含 .finalrun/ 目录的项目中安全使用已发布的 finalrun CLI,用于移动端测试工作区的校验、执行、报告与排障。默认面向应用仓库使用者,而非 monorepo 贡献者流程。
安装与就绪检查:npm install -g @finalrun/finalrun-agent,随后 finalrun --help;本地 Android 或 iOS 执行前先用 finalrun doctor 检查主机就绪状态。
工作区结构:.finalrun/tests/ 必需;suites/ 仅在使用 finalrun suite 或 --suite 时需要;env/ 与 config.yaml 可选。CLI 不能自动创建该工作区,缺失时应说明并考虑改用 finalrun-generate-test 生成测试。
主要命令:finalrun check 校验选择器、套件、配置、env 绑定与应用覆盖;finalrun test 运行 specs;finalrun suite <suitePath> 运行套件;finalrun doctor 检查本地环境;finalrun runs 列出运行产物(支持 --json);finalrun start-server 启动报告 UI(支持 --port、--dev)。test 与 suite 执行前会校验,校验失败即阻断。
常用标志:--env、--platform(android|ios)、--app(.apk 对应 Android,.app 对应 iOS)、--model、--api-key、--debug、--max-iterations、--suite。显式命令行标志覆盖 config.yaml 默认值。
密钥与提供商:支持 openai、google、anthropic,分别使用 OPENAI_API_KEY、GOOGLE_API_KEY、ANTHROPIC_API_KEY。密钥占位需严格为 ${ENV_VAR};缺失、格式错误或未声明绑定须由用户自行修复或导出环境变量。不得编造或替换密钥值。
安全策略:check、doctor、runs 可直接运行;test、suite、start-server 需先征得同意,因为执行耗时、可能消耗额度,服务器命令会启动后台进程并打开浏览器。
执行后:成功时确认结果并给出报告 URL,不主动追加后续运行建议;失败时读取 result.json、actions/、screenshots/、recording、device.log、runner.log 等产物,用平实语言说明失败位置与设备画面,并给出规格修正、应用缺陷或环境配置等具体建议。
适用场景:仓库内移动端测试的日常校验、执行与排障。限制:需已有 .finalrun/ 工作区;YAML 测试与套件、env 绑定的创建或编辑应交给 finalrun-generate-test,本技能不重复该编写流程。