sc-e2e

E2E 测试技能

全面的端到端测试工作流，支持多种框架和交互式调试。

快速开始

# Run all E2E tests
/sc:e2e run

# Run specific test file
/sc:e2e run --file auth.spec.ts

# Debug failing test
/sc:e2e debug --file auth.spec.ts --ui

# Record user interactions
/sc:e2e record --url /login

# Run with tracing enabled
/sc:e2e trace --file checkout.spec.ts

# Generate test scaffold
/sc:e2e generate spec user-profile

# View test report
/sc:e2e report

行为流程

1. 检测 - 识别 E2E 框架（Playwright、Cypress、Selenium）
2. 配置 - 从参数中解析模式和选项
3. 执行 - 运行所选模式
4. 分析 - 解析结果，识别失败项
5. 交互 - 提供调试、重新运行或修复选项
6. 报告 - 呈现结果并提供可执行的后续步骤

标志

标志	类型	默认值	描述
--file	字符串	-	要作为目标的特定测试文件
--grep	字符串	-	按名称模式筛选测试
--headed	布尔值	false	在有头浏览器模式下运行
--workers	整数	auto	并行工作线程数
--ui	布尔值	false	打开框架 UI 模式
--url	字符串	/	录制模式的起始 URL
--output	字符串	-	生成代码的输出文件
--framework	字符串	auto	强制指定框架：playwright、cypress、selenium

框架检测

根据项目配置自动检测 E2E 框架：

框架	检测方式	配置文件
Playwright	package.json 中的 @playwright/test	playwright.config.ts
Cypress	package.json 中的 cypress	cypress.config.ts
Selenium	package.json 中的 selenium-webdriver	wdio.conf.js

# Detection logic
if [ -f "playwright.config.ts" ] || [ -f "playwright.config.js" ]; then
  FRAMEWORK="playwright"
elif [ -f "cypress.config.ts" ] || [ -f "cypress.config.js" ]; then
  FRAMEWORK="cypress"
elif [ -f "wdio.conf.js" ] || [ -f "wdio.conf.ts" ]; then
  FRAMEWORK="selenium"
fi

模式 1：run - 执行测试

运行 E2E 测试，可选筛选条件和配置。

Playwright

npx playwright test [--grep "pattern"] [--headed] [--workers N] [file]

Cypress

npx cypress run [--spec "file"] [--headed] [--browser chrome]

运行后分析

测试执行后，解析输出并提供交互式选项：

Test run complete: X passed, Y failed

  [r] Re-run failed tests
  [d] Debug failing test
  [t] View trace/screenshot
  [f] Fix with /sc:tdd
  [a] Run all tests
  [q] Quit

模式 2：debug - 交互式调试

启动框架的调试模式，逐步执行测试。

Playwright 调试选项

选项	命令	使用场景
UI 模式	npx playwright test --ui	通过时间旅行进行可视化逐步执行
检查器	PWDEBUG=1 npx playwright test	选择器构建器 + 断点
慢动作	npx playwright test --headed --slowmo=500	观察测试执行过程

Cypress 调试选项

选项	命令	使用场景
打开模式	npx cypress open	交互式测试运行器
调试	npx cypress run --headed --no-exit	失败时保持浏览器打开

调试技巧

• 使用 await page.pause()（Playwright）或 cy.pause()（Cypress）设置断点
• 检查 test-results/ 或 cypress/screenshots/ 中的屏幕截图
• 使用跟踪查看器进行时间旅行调试

模式 3：record - 录制用户交互

使用代码生成工具录制浏览器交互并生成测试代码。

Playwright

npx playwright codegen http://localhost:3000[url-path]

Cypress

npx cypress open  # Use Cypress Studio for recording

录制后

1. 检查生成的代码
2. 提供转换为页面对象模式的选项：
   • 将选择器提取到页面对象类中
   • 将操作转换为可复用的方法
   • 根据现有模式添加断言

模式 4：trace - 跟踪

运行启用了跟踪的测试，或查看现有跟踪。

Playwright

# Run with tracing
npx playwright test --trace on [file]

# View trace
npx playwright show-trace test-results/[trace].zip

Cypress

# Traces are auto-captured in cypress/videos/
# Screenshots in cypress/screenshots/

模式 5：generate - 测试脚手架

按照项目模式生成测试文件。

generate spec <name>

创建新的测试规范文件，其中包含：

• 框架的导入语句
• 带有页面名称的 describe 块
• 包含登录/导航的 beforeEach
• 针对常见场景的空测试框架

generate page <name>

创建新的页面对象，其中包含：

• 从目标页面组件中提取的选择器常量
• 操作方法（点击、填写、导航）
• 断言辅助方法（expectLoaded、expectError）

页面对象模式

// Playwright page object template
import { Page, Locator, expect } from '@playwright/test';

export class UserProfilePage {
  readonly page: Page;
  readonly nameInput: Locator;
  readonly saveButton: Locator;

  constructor(page: Page) {
    this.page = page;
    this.nameInput = page.getByTestId('profile-name');
    this.saveButton = page.getByTestId('profile-save');
  }

  async goto(): Promise<void> {
    await this.page.goto('/profile');
  }

  async updateName(name: string): Promise<void> {
    await this.nameInput.fill(name);
    await this.saveButton.click();
  }

  async expectLoaded(): Promise<void> {
    await expect(this.nameInput).toBeVisible();
  }
}

模式 6：report - 查看报告

查看并分析测试报告。

Playwright

npx playwright show-report

Cypress

# Open Mochawesome report if configured
open cypress/reports/index.html

摘要输出

## E2E Test Report

| Suite | Tests | Passed | Failed | Skipped | Duration |
|-------|-------|--------|--------|---------|----------|
| Auth | 5 | 5 | 0 | 0 | 12.3s |
| Dashboard | 8 | 7 | 1 | 0 | 24.1s |
| Checkout | 3 | 3 | 0 | 0 | 18.7s |

**Total**: 16 tests, 15 passed, 1 failed (93.8%)

环境变量

变量	用途
BASE_URL	测试用的应用 URL（默认值：http://localhost:3000）
E2E_USERNAME	测试用户凭据
E2E_PASSWORD	测试用户密码
CI	调整 CI 的工作进程数和重试次数
PWDEBUG	启用 Playwright Inspector

MCP 集成

PAL MCP

工具	使用时机	用途
mcp__pal__debug	测试失败	分析 E2E 失败的根本原因
mcp__pal__codereview	生成的测试	审查测试质量和覆盖率
mcp__pal__apilookup	框架文档	获取最新的 Playwright/Cypress API 文档

PAL 使用模式

# Debug failing E2E test
mcp__pal__debug(
    step="E2E test 'checkout flow' fails on payment step",
    hypothesis="Selector changed after UI update",
    confidence="medium",
    relevant_files=["tests/e2e/checkout.spec.ts", "src/components/PaymentForm.tsx"]
)

# Review generated page object
mcp__pal__codereview(
    review_type="quick",
    step="Review generated page object for completeness",
    relevant_files=["tests/e2e/pages/checkout.page.ts"]
)

Rube MCP

工具	使用时机	用途
mcp__rube__RUBE_MULTI_EXECUTE_TOOL	CI 集成	将 E2E 结果发布到 Slack，更新工单

工具协作

• Bash - 框架 CLI 命令（playwright、cypress）
• Glob - 查找测试文件、扫描页面组件
• Grep - 从组件中提取选择器、解析测试输出
• Read - 检查组件以生成页面对象
• Write - 生成测试文件和页面对象

相关技能

• /sc:test - 单元和集成测试
• /sc:tdd - 测试驱动开发工作流
• /sc:pr-check - PR 前验证，包括 E2E
• /sc:implement - 实现功能并生成测试