前言¶

用 Cypress 写自动化时，常见问题不是「会不会 cy.visit」，而是链式命令和 async/await 混用、硬编码 cy.wait(5000)、用脆弱 class 选择器，以及本地能跑、上云或进 CI 时配置对不上。让通用大模型直接生成用例，往往也会踩同一套坑。

下面介绍 TestMu AI 在 LambdaTest agent-skills 仓库中维护的 cypress-skill：把资深 QA 在 Cypress 上的执行目标判断、目录约定、反模式与校验清单写进 Skill，在用户提到 Cypress、cy.*、E2E 或组件测试时，引导生成更接近生产习惯的 JavaScript/TypeScript 用例，并区分本地运行与 TestMu AI（原 LambdaTest）云执行路径。

这是什么¶

cypress-skill 是一条面向 e2e-testing 的 Agent Skill（SKILL.md 元数据版本 1.0，MIT 许可，作者 TestMu AI）。

官方描述概括为：生成 production-grade 的 Cypress E2E 与 component 测试，语言为 JavaScript 或 TypeScript；支持 本地执行 与 TestMu AI cloud。

典型触发词包括：Cypress、cy.、component test、E2E test、TestMu、LambdaTest，以及 cy.visit、cy.get、cy.intercept 等具体命令场景。该 Skill 在 VoltAgent/awesome-agent-skills 收录的 TestMu AI 官方 Skill 之列，可与 Cursor、Claude Code、Codex CLI 等支持 Agent Skills 的工具配合使用（具体挂载路径以各工具文档为准；本 Skill 源码目录为仓库下的 cypress-skill/）。

核心功能¶

执行目标（本地 vs 云）¶

Skill 内嵌决策：用户要「测试 / 自动化」时，若提到 cloud、TestMu、LambdaTest、cross-browser，则走 TestMu AI cloud（通过 cypress-cli plugin）；若提到 locally、open、headed，则走本地 npx cypress open；意图不明确时 默认本地，并提示云侧选项。

测试类型与目录¶

编码规范（Skill 会强调的部分）¶

命令链（CRITICAL）：Cypress 用链式 API，不用 async/await，不把 cy.get() 赋给变量再延后使用。

选择器优先级（从高到低）：[data-cy] → [data-testid] → cy.contains 文本 → #id → class（标注为 fragile）。

反模式对照（节选）：cy.wait(5000) 应改为 cy.intercept() + cy.wait('@alias')；避免测第三方真实站点，改用 stub/mock；避免单个臃肿的 beforeEach 塞满所有逻辑，倾向多 spec、更好隔离。

校验工作流（Validation Workflow）：

1. 禁止任意数字等待（零 cy.wait(number)，用 intercept）
2. 选择器优先 data-cy
3. 纯 Cypress 链式，不用 async/await
4. 断言用 .should() 链，而非手写判断
5. 用例隔离；鉴权可配合 cy.session()

参考文档与进阶 Playbook¶

Skill 指向仓库内 reference 文件，例如：

安装与启用¶

官方发布形态为 GitHub 仓库子目录，无单独 npm 包名在已抓取资料中列出。获取方式：

1. 打开 https://github.com/LambdaTest/agent-skills/tree/main/cypress-skill
2. 将 cypress-skill 目录（含 SKILL.md 与 reference/）按你所用 Agent 产品的 Skills 加载说明 加入技能路径

元数据片段（名称与触发场景）：

name: cypress-skill
description: >
  Generates production-grade Cypress E2E and component tests in JavaScript
  or TypeScript. Supports local execution and TestMu AI cloud.
languages:
  - JavaScript
  - TypeScript
category: e2e-testing
license: MIT
metadata:
  author: TestMu AI
  version: "1.0"

各 IDE/CLI 的安装字段（如 Cursor Rules、.claude/skills 等）以对应产品文档为准；资料中未给出 cypress-skill 专用的单行安装命令，此处不臆造。

典型用法¶

基础 E2E 结构¶

Skill 推荐的 describe / beforeEach / it 模式如下（选择器以 data-cy 为例）：

describe('Login', () => {
  beforeEach(() => {
    cy.visit('/login');
  });

  it('should login with valid credentials', () => {
    cy.get('[data-cy="username"]').type('user@test.com');
    cy.get('[data-cy="password"]').type('password123');
    cy.get('[data-cy="submit"]').click();
    cy.url().should('include', '/dashboard');
    cy.get('[data-cy="welcome"]').should('contain', 'Welcome');
  });

  it('should show error for invalid credentials', () => {
    cy.get('[data-cy="username"]').type('wrong@test.com');
    cy.get('[data-cy="password"]').type('wrong');
    cy.get('[data-cy="submit"]').click();
    cy.get('[data-cy="error"]').should('be.visible');
  });
});

网络拦截¶

Stub 登录接口并断言请求体，或等待真实 API：

cy.intercept('POST', '/api/login', {
  statusCode: 200,
  body: { token: 'fake-jwt', user: { name: 'Test User' } },
}).as('loginRequest');

cy.get('[data-cy="submit"]').click();
cy.wait('@loginRequest').its('request.body').should('deep.include', {
  email: 'user@test.com',
});

cy.intercept('GET', '/api/dashboard').as('dashboardLoad');
cy.visit('/dashboard');
cy.wait('@dashboardLoad');

自定义命令与 cy.session¶

在 cypress/support/commands.js 中封装登录，减少重复 UI 步骤：

Cypress.Commands.add('login', (email, password) => {
  cy.session([email, password], () => {
    cy.visit('/login');
    cy.get('[data-cy="username"]').type(email);
    cy.get('[data-cy="password"]').type(password);
    cy.get('[data-cy="submit"]').click();
    cy.url().should('include', '/dashboard');
  });
});

// Usage in tests
cy.login('user@test.com', 'password123');

本地常用命令（Quick Reference）¶

TestMu AI / LambdaTest 云执行¶

cypress.config.js 中通过 setupNodeEvents 接入 LambdaTest 插件；云侧另有 lambdatest-config.json 示例（账号来自环境变量 LT_USERNAME、LT_ACCESS_KEY，浏览器矩阵与 run_settings 如 parallels、specs 等）。运行命令：

npx lambdatest-cypress run

云配置示例结构（字段名以官方 reference 为准）：

{
  "lambdatest_auth": {
    "username": "${LT_USERNAME}",
    "access_key": "${LT_ACCESS_KEY}"
  },
  "browsers": [
    { "browser": "Chrome", "platform": "Windows 11", "versions": ["latest"] },
    { "browser": "Firefox", "platform": "macOS Sequoia", "versions": ["latest"] }
  ],
  "run_settings": {
    "build_name": "Cypress Build",
    "parallels": 5,
    "specs": "cypress/e2e/**/*.cy.js"
  }
}

适用场景与注意¶

适合：团队已选或评估 Cypress 做 Web E2E / 组件测试；希望在 Agent 对话里一次性得到符合链式 API、intercept、稳定选择器约定的用例骨架；需要在同一套 Skill 逻辑下切换本地调试与 TestMu AI 云、跨浏览器执行。

注意：

• Skill 约束的是生成与审查习惯，不能替代你项目里真实的 cypress.config、依赖版本与 CI 密钥配置。
• 云路径依赖 LambdaTest/TestMu 的 Cypress CLI 与账号；本地默认不自动上云。
• 进阶主题（Playwright 竞品、非 Cypress 栈）不在本 Skill 范围内；同仓库另有其他测试框架 Skill，需另选对应条目。

结尾¶

cypress-skill 把 Cypress 的执行分流、目录约定、反模式表、校验清单和云集成要点写进 Agent 可读的 Skill，减少「能跑但不稳」的生成代码。若你正在搭建测试类 Agent Skill 体系，可从 Cypress 这条主线把 E2E 规范固定下来，再按需接 reference 与云配置。

官方地址：https://github.com/LambdaTest/agent-skills/tree/main/cypress-skill