1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | cypress-flake-fixer-github-awesome-copilot |
| 作者/维护者 | 社区贡献者 qlqlmi(2026-10-10 提交),收录于 GitHub 官方合集仓库 github/awesome-copilot |
| 来源链接 | https://github.com/github/awesome-copilot/tree/main/skills/cypress-flake-fixer |
| 许可证 | MIT(合集仓库许可证,来自 GitHub API) |
| GitHub Stars | 合集仓库整体约 40,000(来自 GitHub API);该数字属整个合集,不代表本技能自身热度 |
| Forks | 合集仓库整体约 5,100(来自 GitHub API) |
| 最新版本 | 无版本号;子目录首次提交为 2026-10-10(来自 GitHub API commits) |
| 安装方式 | npx skills add https://github.com/github/awesome-copilot --skill cypress-flake-fixer,或复制 skills/cypress-flake-fixer/ 到目标 agent 的 skills 目录 |
2. 功能介绍与亮点
专门审计并修复已有 Cypress 测试套件里“时灵时不灵”(flaky)的写法,并检查 Cypress 12 至 16 已移除的 API。
- 自带零依赖扫描器:
scripts/scan-cypress.mjs(约 500 行,只需 Node 18+,不必安装 Cypress),识别固定cy.wait(数字)、把命令返回值赋给变量、async/await、{ force: true }、动作后继续链式调用、.then()内一次性expect()、条件测试,以及Cypress.env()、cy.exec()、cy.server()/cy.route()等被移除的 API。支持--json、--strict、--list-rules,并按项目package.json里的 Cypress 主版本把问题分为 error / warn。 - 有顺序的修复流程:先跑 20 次取失败基线,再按“错误用法 → 时间等待 → 重试链断裂 → force → 状态泄漏 → 选择器”的次序修,每类规则单独提交,便于二分回退。
- “替换而非删除”:对每个
cy.wait(n)要求先弄清它在等什么(网络请求、渲染、防抖、动画、水合),再用对应的cy.intercept别名、断言或cy.clock()替换;明确禁止靠加长超时、加retries或force: true掩盖问题。 - 踩坑清单:如
cy.intercept()必须在请求发出前注册、.should('not.exist')会在元素尚未渲染时直接通过、Next.js 等服务端渲染应用在水合完成前会吞掉点击、Cypress 16 把按键间隔默认值从 10ms 改为 0 等。 - 附带参考:
references/anti-patterns.md(每条规则的前后对照代码)与references/removed-apis.md(各主版本被移除的 API 与迁移代码)。
3. 适用场景
所属分类:工程效率与代码质量(测试稳定性与调试)。
适合:Cypress 用例本地通过、CI 偶发失败的前端 / 测试工程师;出现 “detached from the DOM”、“timed out retrying” 报错的团队;正在把 Cypress 升级到 15 / 16、想先排查被移除 API 的项目。不适合从零编写新用例(该场景看编码规范即可)。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 ✅ | 标准 SKILL.md(仅 name / description),放入 skills 目录即可触发;扫描器已在 Node 22 下实际运行并输出预期告警 |
| Codex | 需手动引用 ⚠️ | Codex 不会自动扫描 ~/.codex/skills,需在对话中指明技能路径;扫描器只依赖 Node,沙箱内可运行 |
| OpenClaw | 未验证 ❓ | 格式为通用 Agent Skills,未找到 OpenClaw 实测记录 |
| Hermes Agent | 原生支持 ✅ | Hermes 按路径扫描子目录探测 SKILL.md,可直接发现 |
5. 推荐理由
Cypress 的“偶发失败”多数来自少数几种固定写法,却常被“加长等待、加重试”一路掩盖。这个技能把可机器识别的部分交给扫描器、需要判断的部分写成带取舍的流程:先量基线、再按优先级修、最后用同样次数的重跑验证,并且要求把测试暴露出的应用缺陷单独上报而不是在测试里绕过。对正在升级 Cypress 的项目,removed-apis 清单与按版本分级的告警也能提前暴露升级阻塞点。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 4 | 2026-10-10 刚加入合集,尚无安装量与具名讨论;合集仓库约 4 万 stars 属整个合集,不计入本技能 |
| 可用性 | 9 | 一条命令即可扫描,文档含流程、判断表、报告模板与排障表;扫描器零依赖;近日刚提交;无付费依赖 |
| 安全性 | 9 | 扫描器只读取本地文件,源码中无网络请求、无子进程调用、无写盘操作;其余为纯提示词;许可证明确 |
安全检查清单:① 技能要求 agent 运行 node 扫描器与项目自己的 npx cypress run,修改范围限于测试代码 ✅;② 扫描器不联网,Cypress 运行按项目自身配置 ✅;③ 不要求任何凭据 ✅;④ 未发现可疑指令或夹带推广,并明确“只改测试代码、不用加超时 / retries / force 掩盖失败” ✅;⑤ 作者为合集社区贡献者,合集由 GitHub 维护 ✅;⑥ MIT ✅;⑦ 2026-10-10 提交 ✅。
综合评分:7.33(三项均值)
7. 跟同类 Skills 相比的优势
| 方案 | 核心定位 | 与本技能的差异 |
|---|---|---|
| cypress-skill(LambdaTest agent-skills) | 编写 Cypress 用例并接入 LambdaTest 云 | 偏“写新测试”;本技能专攻存量套件的反模式审计与修复 |
| e2e-testing-patterns(wshobson/agents) | 通用 E2E 测试模式指南 | 不绑定 Cypress,也无扫描器;本技能含针对 Cypress 12–16 的规则与移除 API 清单 |
| ESLint 插件 eslint-plugin-cypress | 编辑器内静态规则 | 只提示语法层问题;本技能还给出“该用什么条件替换等待”的判断流程与验证方法 |
| Cypress 官方迁移指南 | 文档形式列出各版本变更 | 需人工逐条对照;本技能把其中被移除的 API 做成可批量扫描的规则 |
差异化:同时具备机器扫描、有序修复流程和验证闭环,且锁定 Cypress 12–16;代价是只服务 Cypress,扫描结果为启发式,需逐处确认。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
- 扫描器支持行内
// cy-scan-ignore CY0xx标注误报; - 技能随合集一并发布,合集内另有面向其他技术栈的测试类技能。
10. 安装使用方式
- 通用方式(跨 agent):
npx skills add https://github.com/github/awesome-copilot --skill cypress-flake-fixer - 手动安装:把仓库
skills/cypress-flake-fixer/整个文件夹复制到目标 agent 的 skills 目录(如 Claude Code 的~/.claude/skills/) - 安装后无需重启;在对话中说“帮我修这个项目里不稳定的 Cypress 用例”或“升级 Cypress 16 前先扫一遍”即可触发。需要 Node.js 18 或更新版本。
11. 注意事项
- 扫描结果是启发式的,需打开对应位置确认再改;
- 修复要求重复运行用例(建议先跑 20 次取基线),在 CI 配额紧张的项目里会消耗较多时间;
- 技能刚发布,规则覆盖与对新版 Cypress 的适配会随上游更新变化;
- 只修改测试代码;若发现是应用本身的竞态或缺失加载态,需另行处理。