1. 项目概述为AI编码助手注入专业的Cypress测试技能如果你正在使用Claude Code、Cursor这类AI编码助手来辅助开发并且你的项目里恰好有Cypress端到端测试的需求那么你很可能遇到过这样的场景你向助手描述一个测试用例比如“帮我写一个登录页面的Cypress测试”它生成的代码要么是过时的语法要么是脆弱的CSS选择器要么完全忽略了网络请求的模拟和状态管理。你需要反复纠正甚至自己重写这并没有节省多少时间。这正是cypress-agent-skill这个项目要解决的问题。它不是一个普通的Cypress教程库而是一个专门为AI编码助手AI Agent设计的“技能包”旨在将生产级别的Cypress测试最佳实践直接“灌输”给这些助手让它们能写出更健壮、更专业、更可维护的测试代码。简单来说这个项目提供了一个结构化的知识库其核心是一个名为SKILL.md的文件。当AI助手如OpenClaw、Claude Code被配置加载了这个技能后它在处理任何与Cypress测试相关的请求时都会优先参考这份文档中的模式和规范。这相当于给你的AI助手配备了一位资深的Cypress测试专家作为顾问。项目覆盖了从基础的选择器策略、断言链式调用到高级的cy.session认证、网络拦截cy.intercept、组件测试、CI/CD并行化以及消除测试“flake”非确定性失败等方方面面。所有内容都以AI易于理解和应用的方式组织并附带可直接复制粘贴的示例代码。2. 核心设计思路如何让AI“学会”写测试2.1 技能格式与AgentSkills规范这个项目的基石是遵循了AgentSkills社区规范。其核心思想是一个“技能”应该是一个自包含的、结构化的知识单元AI助手可以轻松地安装、读取和应用。项目采用极简的扁平化结构将最重要的SKILL.md文件直接放在仓库根目录。这样做的好处是当AI助手将仓库克隆到其技能目录如~/.openclaw/skills/后无需任何额外的路径导航就能直接访问到核心知识文档。这种设计充分考虑了AI的工作模式——路径越直接信息获取和应用的效率就越高。SKILL.md文件本身并非简单的代码片段堆积。它采用了清晰的Markdown格式并可能包含特定的元数据Frontmatter用于声明技能的适用范围、触发条件等。例如它可以被配置为仅在检测到项目中含有cypress依赖或cypress.config.js文件时才被激活避免在不相关的项目中产生干扰。这种“按需激活”的机制确保了技能使用的精准性和高效性。2.2 知识的分层与组织策略为了让AI既能快速掌握要点又能深入细节项目采用了分层的知识组织方式核心技能文档SKILL.md这是AI首要阅读的“总纲”。它浓缩了Cypress测试最核心、最常用的模式和黄金法则。例如它会开宗明义地强调使用>cy.intercept(GET, /api/users, { fixture: users.json }).as(getUsers); cy.visit(/dashboard); cy.wait(getUsers); // 等待这个特定的请求完成动态响应根据测试场景动态生成响应体或修改请求/响应头。延迟与错误模拟测试加载状态或错误处理逻辑。cy.intercept(POST, /api/login, { statusCode: 401, body: { error: Invalid credentials }, delay: 1000 // 模拟网络延迟 }).as(failedLogin);技能会指导AI为关键的网络请求设置别名.as(aliasName)然后使用cy.wait(aliasName)来显式等待这比使用固定的cy.wait(5000)要可靠得多也是消除因网络延迟导致测试失败flake的关键手段。cy.session()告别重复登录在测试套件中每个测试文件或it块都重新登录一次既慢又增加了不必要的依赖。cy.session()是Cypress的缓存机制可以将登录后的会话包括cookies、localStorage等缓存起来在同一个测试运行器spec的后续测试中复用。// 在 before() 或 beforeEach() 中设置一次即可 beforeEach(() { cy.session(myUserSession, () { cy.visit(/login); cy.get([data-testidemail]).type(userexample.com); cy.get([data-testidpassword]).type(password123); cy.get([data-testidsubmit]).click(); cy.url().should(include, /dashboard); }); cy.visit(/dashboard); // 复用会话直接跳转到登录后页面 });AI会被教导在需要认证的测试套件开头使用此模式并理解其背后的原理首次执行时运行登录逻辑并缓存后续调用时直接恢复缓存极大提升测试速度。3.3 自定义命令与页面对象模型提升代码可维护性当测试规模增长时组织代码至关重要。技能会引导AI采用两种主流模式来构建清晰、可复用的测试代码库。自定义命令Custom Commands将重复的操作如登录、数据准备、通用断言封装成自定义命令存放在cypress/support/commands.js中。这不仅能减少代码重复还能让测试用例读起来更像自然语言。// cypress/support/commands.js Cypress.Commands.add(login, (username, password) { cy.session(session-${username}, () { cy.visit(/login); cy.get([data-testidemail]).type(username); cy.get([data-testidpassword]).type(password); cy.get([data-testidsubmit]).click(); cy.url().should(include, /dashboard); }); cy.visit(/dashboard); }); // 在测试中使用 it(should display user profile, () { cy.login(userexample.com, password123); cy.get([data-testidprofile-name]).should(contain, John Doe); });技能会提供一套常用的自定义命令示例并指导AI如何为这些命令添加TypeScript类型定义以在支持TypeScript的项目中获得完美的代码提示。页面对象模型Page Object Model, POMPOM是一种设计模式将每个页面的元素定位器和页面操作方法封装在一个单独的类中。测试用例则通过操作这些页面对象来完成流程使测试逻辑与UI细节分离。// cypress/pages/LoginPage.js class LoginPage { elements { emailInput: () cy.get([data-testidemail]), passwordInput: () cy.get([data-testidpassword]), submitButton: () cy.get([data-testidsubmit]), errorMessage: () cy.get([data-testiderror-message]), }; visit() { cy.visit(/login); return this; } login(email, password) { this.elements.emailInput().type(email); this.elements.passwordInput().type(password); this.elements.submitButton().click(); } } export default new LoginPage(); // 在测试中使用 import LoginPage from ../pages/LoginPage; it(should login successfully, () { LoginPage.visit().login(userexample.com, password123); cy.url().should(include, /dashboard); });AI通过学习examples/page-objects.cy.js能够掌握如何构建和使用页面对象从而生成结构更优、更易于后期维护的测试代码。4. 高级主题与CI/CD集成4.1 组件测试与视觉回归现代前端开发中组件测试变得越来越重要。Cypress Component Testing允许你像运行端到端测试一样在真实的浏览器中挂载并测试单个Vue、React或Angular组件。技能会指导AI如何配置cypress.config.js以支持组件测试。使用cy.mount()来挂载组件。模拟组件props和事件并断言其渲染输出和行为。将组件测试与端到端测试在同一个框架下统一管理。视觉回归测试是确保UI不发生意外变化的重要手段。技能会介绍如何集成像Percy或Applitools这样的视觉测试平台。AI会学习到在关键的交互或页面加载后调用cy.percySnapshot(homepage logged in)来捕获屏幕截图并上传对比而不是在测试代码中写死像素级的断言。4.2 在CI/CD流水线中稳定运行将Cypress测试集成到持续集成/持续部署CI/CD流水线中是保证代码质量的关键环节。cypress-agent-skill的references/ci.md文档为AI提供了详尽的指南GitHub Actions提供标准的YAML工作流配置包括缓存Cypress二进制文件和node_modules以加速运行以及如何将测试结果生成JUnit报告以便在PR中显示。并行化与负载均衡对于大型测试套件串行运行会非常耗时。技能会指导AI如何利用Cypress Cloud或开源方案如cypress-parallel将测试套件拆分到多个机器上并行运行并合并测试报告。录制与调试指导AI配置recordKey将测试运行过程录制并上传到Cypress Cloud。当测试在CI中失败时开发者可以回放视频、查看截图和每一步的控制台日志这比仅看日志文本要直观得多是排查CI失败问题的利器。环境变量与敏感信息教导AI使用cypress.config.js中的env配置或CI系统的secrets来安全地管理测试环境所需的API密钥、登录凭证等避免硬编码在代码中。5. 实战从安装到编写第一个AI辅助测试让我们以一个具体的例子看看如何利用这个技能提升AI助手的工作效率。假设我们有一个使用Next.js和TypeScript构建的简单任务管理应用现在需要为“创建任务”功能添加Cypress测试。第一步为AI助手安装技能根据你使用的AI助手选择对应的安装命令。例如如果你使用Claude Code并且希望该技能对所有项目生效可以运行git clone https://github.com/KahlilR23/cypress-agent-skill \ ~/.claude/skills/cypress-agent-skill安装后Claude Code在分析你的项目上下文看到package.json里有cypress时就会自动加载这个技能的知识。第二步向AI助手提问现在你可以在Claude Code的聊天框中输入“请为我的任务管理应用编写一个Cypress端到端测试。功能是用户登录后在主页点击‘新建任务’按钮填写标题和描述点击保存然后能在任务列表中看到新创建的任务。请使用>// cypress/e2e/create-task.cy.js describe(Task Creation Flow, () { beforeEach(() { // 使用 cy.session 缓存登录会话避免每个测试重复登录 cy.session(taskUser, () { cy.visit(/login); cy.get([data-testidemail]).type(testexample.com); cy.get([data-testidpassword]).type(password123); cy.get([data-testidsubmit]).click(); cy.url().should(include, /dashboard); }); cy.visit(/dashboard); // 恢复会话直接进入登录后页面 }); it(should create a new task and display it in the list, () { // 1. 拦截创建任务的API请求并返回预设的成功响应 cy.intercept(POST, /api/tasks, { statusCode: 201, body: { id: task-123, title: My New Task, description: This is a test task created via Cypress., completed: false, createdAt: new Date().toISOString(), }, }).as(createTaskRequest); // 为请求设置别名 // 2. 执行UI操作 cy.get([data-testidnew-task-button]).click(); cy.get([data-testidtask-title-input]).type(My New Task); cy.get([data-testidtask-description-textarea]).type(This is a test task created via Cypress.); cy.get([data-testidsave-task-button]).click(); // 3. 等待特定的网络请求完成确保操作已触发 cy.wait(createTaskRequest); // 4. 断言UI更新 // 使用更健壮的断言先找到列表容器再在其中寻找特定任务 cy.get([data-testidtasks-list]) .should(be.visible) .within(() { // within 将后续查找范围限定在此元素内 cy.contains([data-testidtask-item], My New Task).should(exist); }); // 5. 可选验证成功提示消息 cy.get([data-testidnotification]) .should(be.visible) .and(contain.text, Task created successfully); }); it(should display validation error when title is empty, () { // 测试表单验证 cy.get([data-testidnew-task-button]).click(); cy.get([data-testidsave-task-button]).click(); // 直接点击保存不填标题 cy.get([data-testidtask-title-input]) .parent() // 通常错误信息会显示在输入框的父元素或相邻元素中 .find([data-testiderror-message]) .should(be.visible) .and(contain.text, Title is required); }); });你可以看到AI生成的代码已经具备了生产级测试的多个特征使用了>// 不好cy.get([data-testidsubmit]).click(); // 好先断言元素可见或存在再操作 cy.get([data-testidsubmit]).should(be.visible).click(); // 或者等待某个标志性元素出现 cy.get([data-testidloading-spinner]).should(not.exist); cy.get([data-testidsubmit]).click();>