mirror of
https://github.com/sweetwisdom/everything-claude-code-zh.git
synced 2026-03-22 06:20:10 +00:00
364 lines
11 KiB
Markdown
364 lines
11 KiB
Markdown
---
|
||
description: 使用 Playwright 生成并运行端到端测试。创建测试旅程、运行测试、捕获截图/视频/追踪，并上传产物。
|
||
---
|
||
|
||
# E2E 命令
|
||
|
||
此命令调用 **e2e-runner** 智能体（Agent）来使用 Playwright 生成、维护和执行端到端测试（End-to-End Tests/E2E）。
|
||
|
||
## 此命令的作用
|
||
|
||
1. **生成测试旅程（Test Journeys）** - 为用户流创建 Playwright 测试
|
||
2. **运行 E2E 测试** - 在不同浏览器上执行测试
|
||
3. **捕获产物（Artifacts）** - 在失败时捕获截图、视频和追踪（Traces）
|
||
4. **上传结果** - 生成 HTML 报告和 JUnit XML
|
||
5. **识别不稳定测试（Flaky Tests）** - 隔离不稳定的测试
|
||
|
||
## 何时使用
|
||
|
||
在以下场景使用 `/e2e`：
|
||
- 测试关键用户旅程（登录、交易、支付）
|
||
- 验证多步骤流程的端到端运行情况
|
||
- 测试 UI 交互和导航
|
||
- 验证前端与后端之间的集成
|
||
- 为生产环境部署做准备
|
||
|
||
## 工作原理
|
||
|
||
e2e-runner 智能体将执行以下操作：
|
||
|
||
1. **分析用户流**并识别测试场景
|
||
2. 使用页面对象模型（Page Object Model/POM）模式**生成 Playwright 测试**
|
||
3. 在多个浏览器（Chrome、Firefox、Safari）上**运行测试**
|
||
4. 通过截图、视频和追踪**捕获失败信息**
|
||
5. **生成报告**，包含结果和产物
|
||
6. **识别不稳定测试**并推荐修复方案
|
||
|
||
## 使用示例
|
||
|
||
```
|
||
用户：/e2e 测试市场搜索和查看流程
|
||
|
||
智能体 (e2e-runner):
|
||
# E2E 测试生成：市场搜索和查看流程
|
||
|
||
## 识别出的测试场景
|
||
|
||
**用户旅程：** 市场搜索 → 查看结果 → 点击市场 → 查看详情
|
||
|
||
**测试覆盖范围：**
|
||
1. 导航到市场页面
|
||
2. 执行语义搜索
|
||
3. 验证搜索结果
|
||
4. 点击第一个结果
|
||
5. 验证市场详情页面加载
|
||
6. 验证图表渲染
|
||
|
||
## 生成的测试代码
|
||
|
||
```typescript
|
||
// tests/e2e/markets/search-and-view.spec.ts
|
||
import { test, expect } from '@playwright/test'
|
||
import { MarketsPage } from '../../pages/MarketsPage'
|
||
import { MarketDetailsPage } from '../../pages/MarketDetailsPage'
|
||
|
||
test.describe('Market Search and View Flow', () => {
|
||
test('user can search markets and view details', async ({ page }) => {
|
||
// 1. 导航到市场页面
|
||
const marketsPage = new MarketsPage(page)
|
||
await marketsPage.goto()
|
||
|
||
// 验证页面加载
|
||
await expect(page).toHaveTitle(/Markets/)
|
||
await expect(page.locator('h1')).toContainText('Markets')
|
||
|
||
// 2. 执行语义搜索
|
||
await marketsPage.searchMarkets('election')
|
||
|
||
// 等待 API 响应
|
||
await page.waitForResponse(resp =>
|
||
resp.url().includes('/api/markets/search') && resp.status() === 200
|
||
)
|
||
|
||
// 3. 验证搜索结果
|
||
const marketCards = marketsPage.marketCards
|
||
await expect(marketCards.first()).toBeVisible()
|
||
const resultCount = await marketCards.count()
|
||
expect(resultCount).toBeGreaterThan(0)
|
||
|
||
// 截取搜索结果截图
|
||
await page.screenshot({ path: 'artifacts/search-results.png' })
|
||
|
||
// 4. 点击第一个结果
|
||
const firstMarketTitle = await marketCards.first().textContent()
|
||
await marketCards.first().click()
|
||
|
||
// 5. 验证市场详情页面加载
|
||
await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
|
||
|
||
const detailsPage = new MarketDetailsPage(page)
|
||
await expect(detailsPage.marketName).toBeVisible()
|
||
await expect(detailsPage.marketDescription).toBeVisible()
|
||
|
||
// 6. 验证图表渲染
|
||
await expect(detailsPage.priceChart).toBeVisible()
|
||
|
||
// 验证市场名称匹配
|
||
const detailsTitle = await detailsPage.marketName.textContent()
|
||
expect(detailsTitle?.toLowerCase()).toContain(
|
||
firstMarketTitle?.toLowerCase().substring(0, 20) || ''
|
||
)
|
||
|
||
// 截取市场详情截图
|
||
await page.screenshot({ path: 'artifacts/market-details.png' })
|
||
})
|
||
|
||
test('search with no results shows empty state', async ({ page }) => {
|
||
const marketsPage = new MarketsPage(page)
|
||
await marketsPage.goto()
|
||
|
||
// 搜索不存在的市场
|
||
await marketsPage.searchMarkets('xyznonexistentmarket123456')
|
||
|
||
// 验证空状态
|
||
await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
|
||
await expect(page.locator('[data-testid="no-results"]')).toContainText(
|
||
/no.*results|no.*markets/i
|
||
)
|
||
|
||
const marketCount = await marketsPage.marketCards.count()
|
||
expect(marketCount).toBe(0)
|
||
})
|
||
|
||
test('can clear search and see all markets again', async ({ page }) => {
|
||
const marketsPage = new MarketsPage(page)
|
||
await marketsPage.goto()
|
||
|
||
// 初始市场数量
|
||
const initialCount = await marketsPage.marketCards.count()
|
||
|
||
// 执行搜索
|
||
await marketsPage.searchMarkets('trump')
|
||
await page.waitForLoadState('networkidle')
|
||
|
||
// 验证过滤后的结果
|
||
const filteredCount = await marketsPage.marketCards.count()
|
||
expect(filteredCount).toBeLessThan(initialCount)
|
||
|
||
// 清除搜索
|
||
await marketsPage.searchInput.clear()
|
||
await page.waitForLoadState('networkidle')
|
||
|
||
// 验证再次显示所有市场
|
||
const finalCount = await marketsPage.marketCards.count()
|
||
expect(finalCount).toBe(initialCount)
|
||
})
|
||
})
|
||
```
|
||
|
||
## 运行测试
|
||
|
||
```bash
|
||
# 运行生成的测试
|
||
npx playwright test tests/e2e/markets/search-and-view.spec.ts
|
||
|
||
Running 3 tests using 3 workers
|
||
|
||
✓ [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)
|
||
✓ [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)
|
||
✓ [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)
|
||
|
||
3 passed (9.1s)
|
||
|
||
生成的产物:
|
||
- artifacts/search-results.png
|
||
- artifacts/market-details.png
|
||
- playwright-report/index.html
|
||
```
|
||
|
||
## 测试报告
|
||
|
||
```
|
||
╔══════════════════════════════════════════════════════════════╗
|
||
║ E2E 测试结果 ║
|
||
╠══════════════════════════════════════════════════════════════╣
|
||
║ 状态: ✅ 所有测试通过 ║
|
||
║ 总计: 3 个测试 ║
|
||
║ 通过: 3 (100%) ║
|
||
║ 失败: 0 ║
|
||
║ 不稳定: 0 ║
|
||
║ 耗时: 9.1s ║
|
||
╚══════════════════════════════════════════════════════════════╝
|
||
|
||
产物：
|
||
📸 截图: 2 个文件
|
||
📹 视频: 0 个文件 (仅在失败时生成)
|
||
🔍 追踪: 0 个文件 (仅在失败时生成)
|
||
📊 HTML 报告: playwright-report/index.html
|
||
|
||
查看报告: npx playwright show-report
|
||
```
|
||
|
||
✅ E2E 测试套件已就绪，可进行 CI/CD 集成！
|
||
```
|
||
|
||
## 测试产物（Artifacts）
|
||
|
||
测试运行时，会捕获以下产物：
|
||
|
||
**所有测试均会捕获：**
|
||
- 包含时间线和结果的 HTML 报告
|
||
- 用于 CI 集成的 JUnit XML
|
||
|
||
**仅在失败时捕获：**
|
||
- 失败状态的截图
|
||
- 测试过程的录屏视频
|
||
- 用于调试的追踪文件（单步回放）
|
||
- 网络日志
|
||
- 控制台日志
|
||
|
||
## 查看产物
|
||
|
||
```bash
|
||
# 在浏览器中查看 HTML 报告
|
||
npx playwright show-report
|
||
|
||
# 查看特定的追踪文件
|
||
npx playwright show-trace artifacts/trace-abc123.zip
|
||
|
||
# 截图保存在 artifacts/ 目录下
|
||
open artifacts/search-results.png
|
||
```
|
||
|
||
## 不稳定测试检测
|
||
|
||
如果测试间歇性失败：
|
||
|
||
```
|
||
⚠️ 检测到不稳定测试 (FLAKY TEST): tests/e2e/markets/trade.spec.ts
|
||
|
||
测试在 10 次运行中通过了 7 次 (70% 通过率)
|
||
|
||
常见失败原因:
|
||
"Timeout waiting for element '[data-testid="confirm-btn"]'"
|
||
|
||
推荐修复建议:
|
||
1. 添加显式等待: await page.waitForSelector('[data-testid="confirm-btn"]')
|
||
2. 增加超时时间: { timeout: 10000 }
|
||
3. 检查组件中的竞态条件
|
||
4. 验证元素未被动画隐藏
|
||
|
||
隔离建议: 在修复前标记为 test.fixme()
|
||
```
|
||
|
||
## 浏览器配置
|
||
|
||
测试默认在多个浏览器上运行：
|
||
- ✅ Chromium (桌面版 Chrome)
|
||
- ✅ Firefox (桌面版)
|
||
- ✅ WebKit (桌面版 Safari)
|
||
- ✅ 移动版 Chrome (可选)
|
||
|
||
在 `playwright.config.ts` 中进行浏览器配置调整。
|
||
|
||
## CI/CD 集成
|
||
|
||
添加到你的 CI 流水线中：
|
||
|
||
```yaml
|
||
# .github/workflows/e2e.yml
|
||
- name: Install Playwright
|
||
run: npx playwright install --with-deps
|
||
|
||
- name: Run E2E tests
|
||
run: npx playwright test
|
||
|
||
- name: Upload artifacts
|
||
if: always()
|
||
uses: actions/upload-artifact@v3
|
||
with:
|
||
name: playwright-report
|
||
path: playwright-report/
|
||
```
|
||
|
||
## PMX 特有的关键流程
|
||
|
||
对于 PMX，请优先考虑这些 E2E 测试：
|
||
|
||
**🔴 关键 (必须始终通过):**
|
||
1. 用户可以连接钱包
|
||
2. 用户可以浏览市场
|
||
3. 用户可以搜索市场（语义搜索）
|
||
4. 用户可以查看市场详情
|
||
5. 用户可以下单交易（使用测试资金）
|
||
6. 市场正确结算
|
||
7. 用户可以提取资金
|
||
|
||
**🟡 重要:**
|
||
1. 市场创建流程
|
||
2. 用户资料更新
|
||
3. 实时价格更新
|
||
4. 图表渲染
|
||
5. 过滤和排序市场
|
||
6. 移动端响应式布局
|
||
|
||
## 最佳实践
|
||
|
||
**建议 (DO):**
|
||
- ✅ 使用页面对象模型（POM）以提高可维护性
|
||
- ✅ 使用 data-testid 属性作为选择器
|
||
- ✅ 等待 API 响应，而不是任意的超时时间
|
||
- ✅ 对关键用户旅程进行端到端测试
|
||
- ✅ 在合并到主分支前运行测试
|
||
- ✅ 测试失败时查看产物
|
||
|
||
**禁忌 (DON'T):**
|
||
- ❌ 使用脆弱的选择器（CSS 类可能会改变）
|
||
- ❌ 测试实现细节
|
||
- ❌ 针对生产环境运行测试
|
||
- ❌ 忽视不稳定测试
|
||
- ❌ 失败时跳过产物审查
|
||
- ❌ 用 E2E 测试每个边缘情况（应使用单元测试）
|
||
|
||
## 重要注意事项
|
||
|
||
**对于 PMX 的关键点：**
|
||
- 涉及真钱的 E2E 测试必须仅在测试网 (testnet) 或预发布环境 (staging) 运行
|
||
- 严禁针对生产环境运行交易测试
|
||
- 为金融相关的测试设置 `test.skip(process.env.NODE_ENV === 'production')`
|
||
- 仅使用带有少量测试资金的测试钱包
|
||
|
||
## 与其他命令的集成
|
||
|
||
- 使用 `/plan` 识别需要测试的关键旅程
|
||
- 使用 `/tdd` 进行单元测试（更快、更细粒度）
|
||
- 使用 `/e2e` 进行集成和用户旅程测试
|
||
- 使用 `/code-review` 验证测试质量
|
||
|
||
## 相关智能体
|
||
|
||
此命令调用位于以下位置的 `e2e-runner` 智能体：
|
||
`~/.claude/agents/e2e-runner.md`
|
||
|
||
## 快捷命令
|
||
|
||
```bash
|
||
# 运行所有 E2E 测试
|
||
npx playwright test
|
||
|
||
# 运行特定的测试文件
|
||
npx playwright test tests/e2e/markets/search.spec.ts
|
||
|
||
# 在有头模式下运行（可看到浏览器）
|
||
npx playwright test --headed
|
||
|
||
# 调试测试
|
||
npx playwright test --debug
|
||
|
||
# 生成测试代码
|
||
npx playwright codegen http://localhost:3000
|
||
|
||
# 查看报告
|
||
npx playwright show-report
|
||
```
|