triage

排查失败的测试

使用此技能复现、诊断并修复失败的 Shiplight YAML 测试。如果应用出现故障，或当前行为与规范冲突，请报告不一致之处，而不是围绕当前行为重写测试。

使用时机

在以下情况下使用 /triage：

• Shiplight 测试运行失败
• 部署或 UI 更改导致现有测试失败
• 多个测试可能有相同的失败原因
• CI 需要尽力修复或报告问题

在以下情况下跳过 /triage：

• 从头创建新测试；使用 /create-yaml-tests
• 验证 UI 代码更改，但没有失败的测试；使用 /verify
• 测试通过，任务仅涉及质量改进
• 产品正按计划重新设计，测试也需要按计划重写

必需的上下文

编辑 YAML 之前：

1. 阅读 create-yaml-tests 参考指南 project-layout.md、updating-tests.md、test-implementation-guide.md 和 knowledge.md。
2. 阅读与失败区域、环境、身份验证、数据和工具相关的 knowledge/ 笔记。
3. 阅读 specs/tests/ 下匹配的规范（如果存在）。
4. 阅读 shiplight://yaml-test-spec 和 shiplight://schemas/action-entity。

事实依据

来源之间存在冲突时，按以下优先级处理：

1. 用户的明确指示
2. specs/tests/ 中的功能或流程规范
3. 现有 YAML 测试的 goal、步骤 intent 和 VERIFY 断言
4. 当前应用行为
5. specs/context.md 和 knowledge/ 中的项目上下文
6. Agent 文档
7. Agent 推断

如果当前应用行为与规范或测试目标冲突，请报告不一致之处。不要默默改写意图以符合当前行为。

工作流程

1. 复现 — 运行指定目标；如果未提供目标，则运行范围最小的相关测试套件。如果失败看起来是暂时性的，请在编辑前对受影响范围最小的目标重试一次。
2. 了解情况 — 在打开浏览器或更改文件之前，阅读失败输出、相关 YAML、匹配的规范、相关测试以及共享模板／函数／钩子。
3. 按需检查 — 如果日志和文件不足以判断问题，请在浏览器中检查正在运行的应用。根据失败情况收集所需证据：DOM、操作、定位器、控制台日志、网络日志、屏幕截图或录制内容。
4. 最小化修复 — 修改范围最小且正确的部分：YAML、模板、辅助函数、身份验证配置、环境数据或规范。除非通过的测试也存在相同的故障源，否则不要修改它们。
5. 验证并重跑 — 使用 validate_yaml_test 验证已编辑的 YAML，然后重跑范围最小的已更改目标。批量修复后，再重跑一次原始目标。
6. 总结经验 — 如果本次处理带来了可长期复用的经验，或纠正了过时的假设，请更新规范、specs/context.md 或 knowledge/。

防护原则

• 如果失败取决于当前浏览器行为，不要猜测渲染后的 UI。
• 不要删除断言、跳过必需步骤，也不要仅为让测试通过而降低覆盖率。
• 如果产品的预期行为已更改，请先更新匹配的规范，再更新 YAML。
• 如果应用出现故障，请报告应用问题，不要用测试更改来掩盖问题。
• 保留用户的更改和无关工作。
• 优先进行有针对性的修复，避免大范围重写。
• 编辑受影响的步骤时，确保 ACTION 定位器和 VERIFY js: 缓存保持最新，但不要无谓改动无关缓存。
• 在 CI 或非交互模式下，不要等待用户输入。应尽力谨慎处理并记录不确定之处。

常见原因包括定位器过时、用户流程已更改、断言偏差、身份验证过期、时序问题、共享模板／钩子、参数数据无效、环境问题以及真实的应用错误。应依据证据确定最小且正确的修复方案。

报告

排查后，请报告：

• 运行的目标命令及其通过／失败结果
• 更改的文件
• 已修复、已跳过、仍然失败或原本就通过的测试
• 已覆盖或恢复的行为
• 应用／规范不一致或尚未解决的阻碍
• 已更新的知识、上下文或规范