From velocitai
Jumps to the failing page without login to diagnose and fix test failures. Handles locator issues, timeouts, assertions, and page structure changes using browser automation tools.
How this skill is triggered — by the user, by Claude, or both
Slash command
/velocitai:quick-debugThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**跳过从登录到问题节点的完整流程,直接免登到目标页面原地排查。**
跳过从登录到问题节点的完整流程,直接免登到目标页面原地排查。
利用项目已有的 token URL 免登机制,配合浏览器工具直接在问题页面进行 DOM 探索、定位符验证、等待策略调整,修复后原地验证,全程不重跑完整测试流程。
Step 1: 解析失败信息
↓
Step 2: 构造免登跳转 URL
↓
Step 3: 免登跳转到目标页面
↓
Step 4: 诊断问题(决策树)
↓
Step 5: 修复 + 原地验证
从堆栈 / 用户描述提取:失败用例名、错误类型(TimeoutError / AssertionError)、失败定位符、失败时所在 URL。信息不足时读取测试代码反推。
从配置文件读取对应环境的 token。
⚠️ 免登前必须向用户确认 --env(见 agent-behavior P0.2)。
两种情况:
| 情况 | 策略 |
|---|---|
| 目标页面有明确 URL 路径 | 先免登(/entry?token=<JWT>),再导航到目标路径 |
| 目标页面需要交互才能到达(弹窗、新 tab 等) | 免登到最近的可直接访问的父级页面,执行最少量的导航操作到达目标 |
browser_navigate → <base_url>/entry?token=<JWT> → 导航到目标路径 → 验证 is_page_loaded()。免登失败(跳回登录页)→ 提示用户刷新 token。
见下一节「诊断决策树」。
根据诊断结果调用对应 skill:
| 诊断结果 | 调用 skill |
|---|---|
| 定位符问题 | locator-replacer |
| 等待策略问题 | wait-strategy |
| 页面加载断言问题 | page-load-assertion |
| 页面大改版 | 报告用户,建议 gen-page-test 重新生成 |
| 断言预期值变更 | 报告差异,由用户决策是否更新预期值 |
原地验证: 修复后在当前浏览器页面直接验证(用 Playwright MCP 重新执行失败操作),确认无误后建议用户重跑完整测试。
先用 agent-browser 快速扫描当前页面 DOM(未安装时降级到 Playwright MCP),然后根据错误类型走对应分支:
错误类型判定
├── A. 定位符问题(元素找不到 / 匹配多个)
├── B. 超时问题(元素存在但加载慢 / 网络延迟)
├── C. 断言问题(元素存在但内容/状态不符预期)
└── D. 页面结构变化(页面整体改版 / 路由变更)
判定依据: locator.count() == 0 或 strict mode violation(匹配多个)
排查步骤:
修复路径 → 调用 locator-replacer skill
判定依据: TimeoutError 且元素在更长等待后可出现,或 networkidle 未达成
排查步骤:
修复路径 → 调用 wait-strategy skill 或调整超时配置
判定依据: AssertionError,元素存在且可见,但值/状态不符预期
排查步骤:
修复路径 → 报告差异并建议用户决策(通常是业务变更而非代码 bug)
判定依据: is_page_loaded() 失败 或 当前 URL 与预期不一致
排查步骤:
修复路径 → 小范围改动调用 locator-replacer;大范围改版报告用户,建议 gen-page-test
如果归类后排查未果,回退到上一级重新分类。最多回退一次,仍无法定位则整理已收集信息报告用户。
DOM 探索/定位符采集 → agent-browser(优先);精确验证/断言 → Playwright MCP;agent-browser 未安装 → 全程 Playwright MCP(P0.4 降级)。
每次 quick-debug 结束前,必须确认:
npx claudepluginhub danielsuo117/velocitai --plugin velocitaiInvestigates and fixes failing Playwright E2E tests using captured action data, screenshots, DOM snapshots, network requests, and console output.
Debugs Playwright test failures, flakiness, selector issues, timeouts using UI mode, inspector, screenshots, slow-mo, and verbose logging.
Analyzes failed E2E test JSON from /test-e2e, reviews screenshots and specs, fixes app code for root causes like timeouts or missing elements, re-runs tests, and verifies.