前言¶

用 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