finalrun-test-and-fix

FinalRun 测试与修复编排器

你负责本仓库中 FinalRun 覆盖的端到端 生成 → 运行 → 诊断 → 修复 循环。你不会取代 finalrun-generate-test 或 finalrun-use-cli，而是调用它们。你的任务是让循环持续推进：为功能规划测试、执行测试、在失败时读取产物、判断问题出在 应用代码 还是 测试，应用范围最小的修复，然后重新运行，直到测试通过或遇到确实无法解决的阻碍。

如果当前会话已有约定的计划、验收标准和修改文件，请将它们作为主要输入，不要从零开始。

核心原则

• 探索时发现的疑似 Bug 只是待验证假设，不是修复目标。 finalrun-generate-test 在读取源代码并规划测试时，你可能会注意到看起来有问题或与验收标准不一致的代码。此时不要修复。 将其记录为待验证假设，确保生成的测试确实会覆盖该路径，然后让 FinalRun 运行来证实或证伪。测试运行前修复源代码，会掩盖测试实际捕获的行为，并有可能“修复”原本正常的代码。
• 先生成并运行，再修复。 顺序必须严格遵守：先通过 finalrun-generate-test 编写或更新测试，再确保 finalrun check 无错误，然后通过 finalrun-use-cli 执行，只有在此之后才能读取产物并应用修复。即使探索时的假设看起来显而易见，也不要在测试运行前修改应用代码。
• 先修复应用，再修复测试。 运行失败并读取产物后，默认假设是应用未达到验收标准。只有在需求确实变更，或断言有误时，才修改测试（例如，断言依赖短暂显示的 toast/snackbar，或对功能并未保证的位置上下文要求过严）。绝不要只为让测试通过而放宽断言。
• 以产物为准。 根据 CLI 输出的 result.json、actions/、screenshots/、recording.*、device.log 和 runner.log 进行诊断。不要只凭 YAML 猜测，也不要在未读取 CLI 指出的产物前总结失败原因。
• 绝不编造密钥、凭据或环境变量值。 如果运行因缺少 shell 变量或缺少 .finalrun/env/<env>.yaml 绑定而受阻，请将确切的变量名和命令告知用户。不要编造值。
• 持续循环，直到通过或确实受阻。 验证错误、失败步骤和红色运行都不是任务的终点，而是循环的输入。只有运行通过，或执行确实不可能时才停止：没有可用的模拟器/设备、缺少必需的密钥，或用户选择退出。

工作流

1. 探索并生成

调用 finalrun-generate-test。向它提供当前会话的计划、验收标准、修改文件和描述的用户流程，让其步骤 1–4 基于现有上下文构建。由该技能负责 YAML 编写规则、文件夹分组、环境文件处理以及 finalrun check 循环。

探索期间，不要编辑应用源代码。 如果深入分析发现代码看起来可疑或与验收标准不一致，请将其记录为一个待验证假设（一行备注：文件、行号、怀疑的问题，以及会覆盖该问题的测试步骤）。确保生成的测试确实覆盖该路径，让运行结果能够证实或证伪该假设。不要急着“现在就修复”——修复应在第 5 步中、运行产生证据后进行。

只有在所改范围的 finalrun check 无错误后，才返回此处。

2. 运行

调用 finalrun-use-cli 执行受影响的范围。遵循该技能的命令构造方式——命令标志的语义由它负责。简而言之：

• 执行前，询问用户是要重新构建应用，还是针对现有构建运行。 不要悄悄重新构建，也不要假设之前的 --app 产物是最新的。如果用户选择重新构建，先构建，然后传入 --app <fresh artifact>（Android .apk、iOS .app）。如果用户选择使用现有构建，请索要或确认该产物的路径，并将其作为 --app 传入。
• 默认针对刚修改的单个测试规范运行 finalrun test <selectors>，以便快速迭代并立即发现第一个失败。除非用户明确要求执行套件级运行（例如，在签字确认前验证整个功能没有回归），否则不要运行 finalrun suite。
• 如果工作区有多个 .finalrun/env/*.yaml 文件，则传入 --env <name>。
• 如果无法从 --app 扩展名推断平台，则传入 --platform。

如果 CLI 显示运行成功，请停止——附上报告 URL，不要升级处理。

3. 失败时进行分类诊断

如果运行结果为失败，请读取 CLI 列出的产物。其目录结构和读取顺序由 finalrun-use-cli 中的 Post-Execution → On failure 定义——请原样遵循该列表，不要在此重复。向用户说明任何内容之前，至少应读取失败测试的 result.json、失败步骤对应的 actions/ 条目，以及该步骤的屏幕截图。

4. 对失败进行分类

将失败归入以下类别之一。这将决定需要修改的是应用还是测试。

产物中的症状	根本原因	修复目标
actions/ 条目显示 Agent 无法定位描述的元素，但屏幕截图清楚显示了正确的 UI	测试措辞过于严格（位置上下文限制过严、标签错误）	测试——放宽该步骤，删除不必要的位置限定
屏幕截图显示应用状态与验收标准不符（字段缺失、导航错误、数据过期）	应用缺陷	应用代码
runner.log 或验证输出指出存在未解析的 ${variables.*} / ${secrets.*}，或缺少提供方 API 密钥	环境／绑定／密钥不可用	两者都不是——转交处理。 告诉用户需要导出的确切变量；切勿臆造
测试因 Toast／Snackbar 闪烁而不稳定，录屏显示其短暂出现后消失	测试断言了短暂 UI	测试——将断言替换为对持久结果的检查（列表更新、徽标计数、字段更改、屏幕跳转）
device.log 显示发生崩溃，或录屏结束于崩溃对话框	应用崩溃	应用代码
result.json 的失败消息报告 expected_state 不匹配，且屏幕截图确认应用确实处于该状态	需求已更改或断言有误	测试——仅当新行为符合本次会话的验收标准时；否则修改应用代码

如果不完全符合表中任何一类，则默认归为应用代码。

5. 应用修复

• 应用代码修复： 直接在此代码库中编辑。修复应尽量精简——不要重构周边代码，也不要为不可能发生的场景添加防御性分支。
• 测试 YAML 修复： 如果只是微调现有步骤中的措辞或 expected_state 条目，请直接编辑 YAML。如果改动较大（新增设置步骤、新增边界情况覆盖、更改环境绑定、新增功能文件夹），请转交给 finalrun-generate-test，以便一致地应用其规则（幂等设置、允许的操作词汇、位置上下文指南、环境文件结构）。
• 绝不要悄悄删除断言、将 expected_state 弱化为 - The screen is visible，或注释掉失败测试来让运行变为成功。

6. 重新运行

在变更范围内重新运行 finalrun check。如果应用代码有变更，重新运行前先询问用户是否要重新构建，不要擅自重建。用户确认重建后，传入新的 --app 构建产物；否则复用现有构建路径。然后重新运行失败的同一条 finalrun test 命令（继续使用单个 spec、快速失败的路径；除非用户提出要求，否则不要升级为 finalrun suite）。返回步骤 3，循环执行，直至全部通过。

7. 停止条件

满足以下条件时停止循环：

• 运行通过。使用 CLI 提供的报告 URL 报告成功。
• 执行确实受阻：此主机上没有可用设备或模拟器、需要用户才能提供的必需密钥，或用户明确选择退出。在这种情况下，输出供用户在本地运行的确切命令——相关时包括 --app <path>、--env <name> 和 --platform——并明确说明受阻的具体原因。

不要仅仅因为某个步骤失败、出现验证错误或首次修复不起作用就停止。这些都是循环中的输入，不是终止状态。

此技能不负责什么

• 从头编写 YAML、决定文件夹结构，或编辑 .finalrun/env/*.yaml 绑定格式 → 转交给 finalrun-generate-test。
• 讲解 CLI 标志、构建产物布局、主机就绪状态、提供商／模型选择，或 finalrun doctor / finalrun runs / finalrun start-server 的用法 → 转交给 finalrun-use-cli。
• 虚构凭据、擅自放宽断言，或在运行未通过时宣称任务已完成（确实受阻时除外）。

与相关技能的协作

此技能负责协调。它会在循环的每一轮中移交工作：

• 纯粹涉及编写或更新 YAML 测试、测试套件或环境绑定的请求 → finalrun-generate-test。
• 纯粹涉及使用 CLI 运行、验证或读取构建产物的请求 → finalrun-use-cli。
• 涉及调试失败的 FinalRun 运行、端到端验证功能，或使用 FinalRun 测试覆盖 UI 变更并完成收尾的请求 → 使用此技能；此技能会依次调用另外两项技能。