Skip to content

DanielSuo117/velocitai / skills/quick-debug

quick-debug

Verified

测试失败时免登跳转原地排查修复。触发:排查、纠错、debug、定位符失败、超时、元素找不到、断言失败。

FileKindSize
SKILL.mdskill md3.3 KB
references/diagnosis-tree.mdmarkdown2.3 KB

references/diagnosis-tree.md

View on GitHub
# 诊断决策树(主干流程 Step 4 展开)

> 由 [quick-debug](../SKILL.md) 按需加载。走到 Step 4 需要判断根因时才读。

先用 agent-browser 快速扫描当前页面 DOM(未安装时降级到 Playwright MCP),然后根据错误类型走对应分支:

```
错误类型判定
    ├── A. 定位符问题(元素找不到 / 匹配多个)
    ├── B. 超时问题(元素存在但加载慢 / 网络延迟)
    ├── C. 断言问题(元素存在但内容/状态不符预期)
    └── D. 页面结构变化(页面整体改版 / 路由变更)
```

### 分支 A: 定位符问题

**判定依据:** `locator.count() == 0` 或 `strict mode violation`(匹配多个)

**排查步骤:**
1. 用 agent-browser 抓取问题区域的 DOM 快照
2. 对比 PageObject 定位符与实际 DOM,判定原因:类名变更 / 文本变更 / 动态渲染未完成

**修复路径** → 调用 `locator-replacer` skill

### 分支 B: 超时问题

**判定依据:** `TimeoutError` 且元素在更长等待后可出现,或 `networkidle` 未达成

**排查步骤:**
1. 检查当前页面 URL 是否正确(排除导航偏差),目标元素是否存在但不可见(hidden / 被遮挡)
2. 判定原因:隐式等待不够 / SPA 渲染延迟 / 网络接口慢

**修复路径** → 调用 `wait-strategy` skill 或调整超时配置

### 分支 C: 断言问题

**判定依据:** `AssertionError`,元素存在且可见,但值/状态不符预期

**排查步骤:**
1. 获取元素实际文本/属性值,与测试代码预期值对比
2. 判定原因:业务数据变化 / 文案更新 / 环境差异

**修复路径** → 报告差异并建议用户决策(通常是业务变更而非代码 bug)

### 分支 D: 页面结构变化

**判定依据:** `is_page_loaded()` 失败 或 当前 URL 与预期不一致

**排查步骤:**
1. 用 agent-browser 抓取全页面快照,与 PageObject 定位符批量比对
2. 判定原因:路由变更 / 页面改版 / 权限变化导致重定向

**修复路径** → 小范围改动调用 `locator-replacer`;大范围改版报告用户,建议 `gen-page-test`

### 回退机制

如果归类后排查未果,回退到上一级重新分类。最多回退一次,仍无法定位则整理已收集信息报告用户。
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall