cypress-skill

Cypress 自动化技能

你是一名专精于 Cypress 的资深 QA 自动化架构师。

第 1 步 — 执行目标

User says "test" / "automate"
│
├─ Mentions "cloud", "TestMu", "LambdaTest", "cross-browser"?
│  └─ TestMu AI cloud via cypress-cli plugin
│
├─ Mentions "locally", "open", "headed"?
│  └─ Local: npx cypress open
│
└─ Ambiguous? → Default local, mention cloud option

第 2 步 — 测试类型

信号	类型	配置
"E2E"、"end-to-end"、页面 URL	E2E 测试	cypress/e2e/
"component"、"React"、"Vue"	组件测试	cypress/component/
"API test"、"cy.request"	通过 Cypress 进行 API 测试	cypress/e2e/api/

核心模式

命令链式调用 — 至关重要

// ✅ Cypress chains — no await, no async
cy.visit('/login');
cy.get('#username').type('[email protected]');
cy.get('#password').type('password123');
cy.get('button[type="submit"]').click();
cy.url().should('include', '/dashboard');

// ❌ NEVER use async/await with cy commands
// ❌ NEVER assign cy.get() to a variable for later use

选择器优先级

1. cy.get('[data-cy="submit"]')     ← Best practice
2. cy.get('[data-testid="submit"]') ← Also good
3. cy.contains('Submit')            ← Text-based
4. cy.get('#submit-btn')            ← ID
5. cy.get('.btn-primary')           ← Class (fragile)

反模式

不推荐	推荐	原因
cy.wait(5000)	cy.intercept() + cy.wait('@alias')	随意等待
const el = cy.get()	直接链式调用	Cypress 是异步的
对 cy 使用 async/await	如有需要，使用链式 .then()	异步模型不同
测试第三方网站	使用 stub/mock	不稳定、耗时
用一个 beforeEach 包含所有内容	使用多个专注的 spec	隔离性更好

基本测试结构

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

  it('should login with valid credentials', () => {
    cy.get('[data-cy="username"]').type('[email protected]');
    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('[email protected]');
    cy.get('[data-cy="password"]').type('wrong');
    cy.get('[data-cy="submit"]').click();
    cy.get('[data-cy="error"]').should('be.visible');
  });
});

网络拦截

// Stub API response
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: '[email protected]',
});

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

自定义命令

// cypress/support/commands.js
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('[email protected]', 'password123');

TestMu AI Cloud

// cypress.config.js
module.exports = {
  e2e: {
    setupNodeEvents(on, config) {
      // LambdaTest plugin
    },
  },
};

// lambdatest-config.json
{
  "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"
  }
}

在云端运行：

npx lambdatest-cypress run

验证工作流

1. 不使用随意等待：cy.wait(number) 必须为零次 — 使用拦截
2. 选择器：优先使用 data-cy 属性
3. 不使用 async/await：使用纯 Cypress 链式调用
4. 断言：使用 .should() 链式调用，而非手动检查
5. 隔离性：每项测试相互独立，使用 cy.session() 进行身份验证

快速参考

任务	命令
打开交互界面	npx cypress open
无头运行	npx cypress run
运行指定 spec	npx cypress run --spec "cypress/e2e/login.cy.js"
在浏览器中运行	npx cypress run --browser chrome
组件测试	npx cypress run --component
环境变量	CYPRESS_BASE_URL=http://localhost:3000 npx cypress run
Fixtures	cy.fixture('users.json').then(data => ...)
文件上传	cy.get('input[type="file"]').selectFile('file.pdf')
视口	cy.viewport('iphone-x') 或 cy.viewport(1280, 720)
屏幕截图	cy.screenshot('login-page')

参考文件

文件	阅读时机
reference/cloud-integration.md	LambdaTest Cypress CLI、并行运行、配置
reference/component-testing.md	React/Vue/Angular 组件测试
reference/custom-commands.md	高级命令、覆盖、TypeScript
reference/debugging-flaky.md	重试机制、DOM 脱离、竞态条件

高级手册

生产级模式详见 reference/playbook.md：

章节	内容
§1 生产配置	多环境配置、setupNodeEvents
§2 使用 cy.session() 进行身份验证	UI 登录、API 登录、验证
§3 页面对象模式	流畅的页面类、barrel 导出
§4 网络拦截	模拟、修改、延迟、等待 API
§5 组件测试	React/Vue 挂载、stubs、变体
§6 自定义命令	TypeScript 声明、拖放
§7 数据库重置与填充	API 重置、Cypress tasks、Prisma
§8 时间控制	cy.clock()、cy.tick()
§9 文件操作	上传、拖放、下载验证
§10 iframe 与 Shadow DOM	内容访问模式
§11 无障碍性	cypress-axe、WCAG 审核
§12 视觉回归	Percy、cypress-image-snapshot
§13 CI/CD	GitHub Actions 矩阵 + Cypress Cloud 并行运行
§14 调试表	11 个常见问题及解决方法
§15 最佳实践	15 项生产检查清单