{"answer":"使用 Playwright 和 Cypress 构建稳定高效的 E2E 测试套件:覆盖核心链路,消除不稳定测试,集成 CI/CD。"}
E2E测试模式,测试用户的功能,而不是代码的操作.是一项面向实际任务的技能,主要用于E2E测试证明系统整体运作——它们是你运送的信心.;OpenClaw / Moltbot / Clawbot.;
使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。
执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。该技能适合用于一次性任务,也可以接入自动化工作流,与其他技能或上层代理配合完成更完整的业务链路;在组合使用时,应明确每一步的输入输出关系,并避免不同步骤之间出现参数冲突。
测试用户实际执行的操作,而非代码内部如何工作。端到端(E2E)测试验证整个系统是否协同正常运行——它们是你发布上线时的信心保障。
npx clawhub@latest install e2e-testing-patterns
提供构建端到端测试套件的实践模式,确保其:
/
/E2E ← 少量:仅覆盖关键路径(本技能聚焦于此)
/─────
/Integr ← 较多:组件交互、API 协议验证
/────────
/Unit Tests ← 大量:快速、隔离、覆盖边界情况
/────────────
| E2E 测试 ✓ | 非 E2E 测试 ✗ |
|---|---|
| 关键用户路径(登录 → 仪表盘 → 执行操作 → 注销) | 单元级逻辑(应使用单元测试) |
| 多步骤流程(结算流程、新手引导向导) | API 协议(应使用集成测试) |
| 跨浏览器兼容性验证 | 边界情况(执行过慢,应使用单元测试) |
| 真实 API 集成验证 | 内部实现细节 |
| 身份认证流程 | 组件视觉状态(应使用 Storybook) |
经验法则:若该功能损坏将对业务造成严重冲击,则必须使用 E2E 测试;若仅带来不便,则优先采用更快的单元测试或集成测试。
| 原则 | 原因 | 实践方式 |
|---|---|---|
| 测试行为,而非实现 | 可抵御代码重构 | 断言用户可见的结果,而非 DOM 结构 |
| 测试相互独立 | 支持并行执行,便于调试 | 每个测试自行创建数据,并在执行后清理 |
| 确定性等待 | 避免偶发性失败 | 等待特定条件满足,而非固定超时 |
| 稳定的选择器 | 可抵御 UI 变更 | 使用 data-testid、角色(role)、标签(label)——切勿使用 CSS 类名 |
| 快速反馈 | 开发者可高频运行 | 模拟外部服务、并行执行、分片运行 |
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
export default defineConfig({
testDir: "./e2e",
timeout: 30000,
expect: { timeout: 5000 },
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: [["html"], ["junit", { outputFile: "results.xml" }]],
use: {
baseURL: "http://localhost:3000",
trace: "on-first-retry",
screenshot: "only-on-failure",
video: "retain-on-failure",
},
projects: [
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
{ name: "firefox", use: { ...devices["Desktop Firefox"] } },
{ name: "webkit", use: { ...devices["Desktop Safari"] } },
{ name: "mobile", use: { ...devices["iPhone 13"] } },
],
});
封装页面逻辑,使测试用例读起来如同用户故事。
// pages/LoginPage.ts
import { Page, Locator } from "@playwright/test";
export class LoginPage {
readonly page: Page;
readonly emailInput: Locator;
readonly passwordInput: Locator;
readonly loginButton: Locator;
readonly errorMessage: Locator;
constructor(page: Page) {
this.page = page;
this.emailInput = page.getByLabel("Email");
this.passwordInput = page.getByLabel("Password");
this.loginButton = page.getByRole("button", { name: "Login" });
this.errorMessage = page.getByRole("alert");
}
async goto() {
await this.page.goto("/login");
}
async login(email: string, password: string) {
await this.emailInput.fill(email);
await this.passwordInput.fill(password);
await this.loginButton.click();
}
}
// tests/login.spec.ts
import { test, expect } from "@playwright/test";
import { LoginPage } from "../pages/LoginPage";
test("成功登录后跳转至仪表盘", async ({ page }) => {
const loginPage = new LoginPage(page);
await loginPage.goto();
await loginPage.login("user@example.com", "password123");
await expect(page).toHaveURL("/dashboard");
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
});
自动创建并清理测试所需数据。
// fixtures/test-data.ts
import { test as base } from "@playwright/test";
export const test = base.extend<{ testUser: TestUser }>({
testUser: async ({}, use) => {
// 初始化:创建测试用户
const user = await createTestUser({
email: `test-${Date.now()}@example.com`,
password: "Test123!@#",
});
await use(user);
// 清理:删除测试用户
await deleteTestUser(user.id);
},
});
// 使用示例 — testUser 在测试前创建,测试后自动清理
test("用户可更新个人资料", async ({ page, testUser }) => {
await page.goto("/login");
await page.getByLabel("Email").fill(testUser.email);
// ...
});
切勿使用固定超时。始终等待明确的条件达成。
// ❌ 不稳定:固定超时
await page.waitForTimeout(3000);
// ✅ 稳定:等待具体条件
await page.waitForLoadState("networkidle");
await page.waitForURL("/dashboard");
// ✅ 最佳实践:自动等待式断言
await expect(page.getByText("Welcome")).toBeVisible();
await expect(page.getByRole("button", { name: "Submit" })).toBeEnabled();
// 等待 API 响应
const responsePromise = page.waitForResponse(
(r) => r.url().includes("/api/users") && r.status() === 200
);
await page.getByRole("button", { name: "Load" }).click();
await responsePromise;
将测试与真实外部服务完全隔离。
test("当 API 失败时显示错误信息", async ({ page }) => {
// 模拟 API 响应
await page.route("**/api/users", (route) => {
route.fulfill({
status: 500,
body: JSON.stringify({ error: "Server Error" }),
});
});
await page.goto("/users");
await expect(page.getByText("Failed to load users")).toBeVisible();
});
test("在网络延迟下优雅降级", async ({ page }) => {
await page.route("**/api/data", async (route) => {
await new Promise((r) => setTimeout(r, 3000)); // 模拟延迟
await route.continue();
});
await page.goto("/dashboard");
await expect(page.getByText("Loading...")).toBeVisible();
});
// cypress/support/commands.ts
declare global {
namespace Cypress {
interface Chainable {
login(email: string, password: string): Chainable;
dataCy(value: string): Chainable>;
}
}
}
Cypress.Commands.add("login", (email, password) => {
cy.visit("/login");
cy.get('[data-testid="email"]').type(email);
cy.get('[data-testid="password"]').type(password);
cy.get('[data-testid="login-button"]').click();
cy.url().should("include", "/dashboard");
});
Cypress.Commands.add("dataCy", (value) => {
return cy.get(`[data-cy="${value}"]`);
});
// 使用示例
cy.login("user@example.com", "password");
cy.dataCy("submit-button").click();
// 模拟 API 响应
cy.intercept("GET", "/api/users", {
statusCode: 200,
body: [{ id: 1, name: "John" }],
}).as("getUsers");
cy.visit("/users");
cy.wait("@getUsers");
cy.get('[data-testid="user-list"]').children().should("have.length", 1);
| 优先级 | 选择器类型 | 示例 | 原因 |
|---|---|---|---|
| 1 | 角色(role)+ 名称(name) | getByRole("button", { name: "Submit" }) |
符合无障碍标准,面向用户 |
| 2 | 标签(label) | getByLabel("Email address") |
符合无障碍标准,语义明确 |
| 3 | data-testid | getByTestId("checkout-form") |
稳定、专为测试设计 |
| 4 | 文本内容 | getByText("Welcome back") |
面向用户,直观可靠 |
| ❌ | CSS 类名 | .btn-primary |
样式变更即失效 |
| ❌ | DOM 结构 | div > form > input:nth-child(2) |
任意结构变动即失效 |
// ❌ 不推荐:脆弱的选择器
cy.get(".btn.btn-primary.submit-button").click();
cy.get("div > form > div:nth-child(2) > input").type("text");
// ✅ 推荐:稳定的选择器
page.getByRole("button", { name: "Submit" }).click();
page.getByLabel("Email address").fill("user@example.com");
page.getByTestId("email-input").fill("user@example.com");
// Playwright 视觉比对
test("首页渲染正确", async ({ page }) => {
await page.goto("/");
await expect(page).toHaveScreenshot("homepage.png", {
fullPage: true,
maxDiffPixels: 100,
});
});
test("按钮不同状态", async ({ page }) => {
const button = page.getByRole("button", { name: "Submit" });
await expect(button).toHaveScreenshot("button-default.png");
await button.hover();
await expect(button).toHaveScreenshot("button-hover.png");
});
// npm install @axe-core/playwright
import AxeBuilder from "@axe-core/playwright";
test("页面无无障碍违规项", async ({ page }) => {
await page.goto("/");
const results = await new AxeBuilder({ page })
.exclude("#third-party-widget") // 排除无法控制的第三方组件
.analyze();
expect(results.violations).toEqual([]);
});
# 以有头模式运行(可观察浏览器行为) npx playwright test --headed # 启动调试模式(单步执行) npx playwright test --debug # 查看失败测试的追踪报告 npx playwright show-report
// 添加测试步骤提升失败报告可读性
test("结算流程", async ({ page }) => {
await test.step("添加商品至购物车", async () => {
await page.goto("/products");
await page.getByRole("button", { name: "Add to Cart" }).click();
});
await test.step("完成结算", async () => {
await page.goto("/checkout");
// ... 若此处失败,可立即定位到具体步骤
});
});
// 暂停执行以便手动检查
await page.pause();
当测试偶发失败时,请逐一核查以下问题:
| 问题 | 修复方案 |
|---|---|
存在固定超时调用 waitForTimeout() |
替换为 waitForSelector() 或基于断言的等待 |
| 页面加载过程中的竞态条件 | 等待 networkidle 状态或特定元素出现 |
| 测试数据污染 | 确保每个测试独立创建并清理自身数据 |
| 动画时序问题 | 等待动画完成,或在测试中禁用动画 |
| 视口尺寸不一致 | 在配置中显式设置 viewport 尺寸 |
| 测试顺序随机导致的问题 | 确保所有测试彼此完全独立 |
| 第三方服务不稳定 | 模拟所有外部 API 调用 |
# GitHub Actions 示例
name: E2E Tests
on: [push, pull_request]
jobs:
e2e:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm ci
- run: npx playwright install --with-deps
- run: npm run build
- run: npm run start & npx wait-on http://localhost:3000
- run: npx playwright test
- uses: actions/upload-artifact@v4
if: failure()
with:
name: playwright-report
path: playwright-report/
waitForTimeout() 或 cy.wait(ms) —— 这会导致测试不稳定且拖慢整体执行速度// 导航
await page.goto("/path");
await page.goBack();
await page.reload();
// 交互操作
await page.click("selector");
await page.fill("selector", "text");
await page.type("selector", "text"); // 逐字符输入
await page.selectOption("select", "value");
await page.check("checkbox");
// 断言
await expect(page).toHaveURL("/expected");
await expect(locator).toBeVisible();
await expect(locator).toHaveText("expected");
await expect(locator).toBeEnabled();
await expect(locator).toHaveCount(3);
// 导航
cy.visit("/path");
cy.go("back");
cy.reload();
// 交互操作
cy.get("selector").click();
cy.get("selector").type("text");
cy.get("selector").clear().type("text");
cy.get("select").select("value");
cy.get("checkbox").check();
// 断言
cy.url().should("include", "/expected");
cy.get("selector").should("be.visible");
cy.get("selector").should("have.text", "expected");
cy.get("selector").should("have.length", 3);
相关专题
热门下载
相关下载
精品课程
共6课时 | 54.7万人学习
共89课时 | 134.3万人学习
共49课时 | 82.7万人学习
最新文章