# 端到端测试 ## 何时使用在以下情况下激活该技能： * 为完整的用户工作流程（登录、CRUD 操作、多页面流程）编写 E2E 测试 * 创建验证完整堆栈的关键路径回归测试 * 测试跨浏览器兼容性（Chromium、Firefox、WebKit） * 端到端验证身份验证流程 * 测试文件上传/下载工作流程 * 编写冒烟测试以进行部署验证请勿将此技能用于： * React组件单元测试（使用`react-testing-patterns`） * Python后端单元/集成测试（使用“pytest-patterns”） * TDD 工作流程实施（使用“tdd-workflow”） * 无需浏览器的 API 合约测试（使用 `pytest-patterns` 和 httpx） ## 说明 ### 测试结构电子到电子/ ├── playwright.config.ts # 全局Playwright配置 ├── 固定装置/ │ ├── auth.fixture.ts # 认证状态设置 │ └── test-data.fixture.ts # 测试数据创建/清理 ├── 页数/ │ ├── base.page.ts # 具有共享方法的基本页面对象 │ ├── login.page.ts # 登录页面对象 │ ├── users.page.ts # 用户列表页面对象 │ └── user-detail.page.ts # 用户详情页对象 ├── 测试/ │ ├── 授权/ │ │ ├── 登录.spec.ts │ │ └── 注销.spec.ts │ ├── 用户/ │ │ ├── create-user.spec.ts │ │ ├── 编辑用户.spec.ts │ │ └── list-users.spec.ts │ └── 烟雾/ │ └── 关键路径.spec.ts └── 实用程序/ ├── api-helpers.ts # 直接API调用进行测试设置 └── test-constants.ts # 共享常量 **命名约定：** * 测试文件：`.spec.ts` * 页面对象：`<页面名称>.page.ts` * 夹具：`<关注>.fixture.ts` * 测试名称：描述用户操作和预期结果的人类可读句子 ### 页面对象模型每个页面都有一个封装选择器和操作的页面对象类。测试从不直接与选择器交互。 **基本页面对象：** // e2e/pages/base.page.ts 从“@playwright/test”导入{ type Page, type Locator }; 导出抽象类 BasePage { 构造函数（受保护的只读页面：页面）{} /** 导航到页面的 URL。 */ 抽象 goto(): Promise; /** 等待页面完全加载。 */ 异步 waitForLoad(): Promise { 等待 this.page.waitForLoadState("networkidle"); } /** 获取 toast/通知消息。 */ 获取 toast(): 定位器 { 返回 this.page.getByRole("alert"); } /** 获取页面标题。 */ 获取标题(): 定位器 { return this.page.getByRole("heading", { level: 1 }); } } **具体页面对象：** // e2e/pages/users.page.ts 从“@playwright/test”导入{ type Page, type Locator }; 从“./base.page”导入{BasePage}；导出类 UsersPage 扩展 BasePage { // ──── 定位器 ────────────────────────────────────────── 只读createButton：定位器；只读搜索输入：定位器；只读用户表：定位器；构造函数（页面：页面）{ 超级（页面）； this.createButton = page.getByTestId("create-user-btn"); this.searchInput = page.getByRole("searchbox", { name: /search users/i }); this.userTable = page.getByRole("table"); } // ──── 动作 ────────────────────────────────────────── 异步 goto(): Promise { 等待 this.page.goto("/users"); 等待 this.waitForLoad(); } 异步 searchFor(查询：字符串): Promise { 等待 this.searchInput.fill(query); // 等待搜索结果更新（去抖）等待 this.page.waitForResponse("**/api/v1/users?*"); } 异步 clickCreateUser(): Promise { 等待 this.createButton.click(); } async getUserRow(email: string): Promise { return this.userTable.getByRole("row").filter({ hasText: email }); } 异步 getUserCount(): Promise { // 标题行减 1 return (await this.userTable.getByRole("row").count()) - 1; } } **页面对象的规则：** * 每页或主要 UI 部分一个页面对象 * 定位器是公共只读属性 * 动作是异步方法 * 页面对象从不包含断言——测试断言 * 页面对象句柄在操作后内部等待 ### 选择器策略 **优先顺序（从高到低）：** 优先|选择器|示例|何时使用 ---|---|---|--- 1 | `数据测试id` | `getByTestId("提交-btn")` |互动元素、动态内容 2 |角色 | `getByRole("button", { name: /save/i })` |按钮、链接、标题、输入 3 |标签| `getByLabel("电子邮件")` |带标签的表单输入 4 |占位符 | `getByPlaceholder("搜索...")` |搜索输入 5 |文字| `getByText("欢迎回来")` |静态文本内容 **切勿使用：** * CSS 选择器（`.class-name`、`#id`）——脆弱，样式更改时中断 * XPath (`//div[@class="foo"]`) -- 不可读，极其脆弱 * DOM 结构选择器 (`div > span:nth-child(2)`) -- 布局更改时中断 **添加 data-testid 属性：** // 在 React 组件中 -- 将 data-testid 添加到交互元素 <按钮 data-testid="create-user-btn" onClick={handleCreate}> 创建用户 // 约定：kebab-case，描述性 // 模式：<动作>-<实体>-<元素类型> // 示例：create-user-btn、user-email-input、delete-confirm-dialog ### 等待策略 **切勿使用硬编码等待：** // 不好：硬编码等待——不稳定、缓慢等待页面.waitForTimeout(3000); // 坏处：睡眠等待新的 Promise((resolve) => setTimeout(resolve, 2000)); **使用显式等待条件：** // 好：等待特定元素出现等待 page.getByRole("标题", { name: "仪表板" }).waitFor(); // 好：等待导航等待 page.waitForURL("/dashboard"); // 好：等待 API 响应等待页面.waitForResponse( （回应）=> response.url().includes("/api/v1/users") && response.status() === 200, ）； // 好：等待网络稳定等待 page.waitForLoadState("networkidle"); // 好：等待元素状态 wait page.getByTestId("submit-btn").waitFor({ state: "visible" }); 等待 page.getByTestId("loading-spinner").waitFor({ state: "hidden" }); **自动等待：** Playwright 在单击、填充等之前自动等待元素可操作。只有断言或复杂的状态转换才需要显式等待。 ### 身份验证状态重用避免在每次测试前登录。保存身份验证状态并重用它。 **设置身份验证状态一次：** // e2e/fixtures/auth.fixture.ts 从“@playwright/test”导入{测试作为基础}；从“路径”导入路径； const AUTH_STATE_PATH = path.resolve("e2e/.auth/user.json"); 导出 const setup = base.extend({}); setup("身份验证", async ({ page }) => { // 执行真实登录等待 page.goto("/login"); 等待 page.getByLabel("电子邮件").fill("testuser@example.com"); 等待 page.getByLabel("密码").fill("TestPassword123!"); 等待 page.getByRole("button", { name: /sign in/i }).click(); // 等待授权完成等待 page.waitForURL("/dashboard"); // 保存登录状态等待 page.context().storageState({ 路径: AUTH_STATE_PATH }); }); **在测试中重用：** // playwright.config.ts 导出默认的defineConfig({ 项目：[ // 安装项目首先运行并保存身份验证状态 { name: "setup", testDir: "./e2e/fixtures", testMatch: "auth.fixture.ts" }, { 名称：“铬”，使用：{ storageState: "e2e/.auth/user.json", // 重用身份验证状态 }, 依赖项：[“设置”]， }, ], }); ### 测试数据管理 **原则：** * 测试创建自己的数据（从不依赖于预先存在的数据） * 测试自行清理（或使用 API 重置） * 使用 API 调用进行设置，而不是 UI 交互（更快、更可靠） **用于测试数据的 API 助手：** // e2e/utils/api-helpers.ts 从“@playwright/test”导入{类型APIRequestContext}；导出类 TestDataAPI { 构造函数（私有请求：APIRequestContext）{} 异步 createUser(数据: { 电子邮件: 字符串; 显示名称: 字符串 }) { const response = wait this.request.post("/api/v1/users", { data }); 返回response.json(); } 异步删除用户（用户ID：数字）{ 等待 this.request.delete(`/api/v1/users/${userId}`); } 异步 createOrder(userId: number, items: Array>) { const response = wait this.request.post("/api/v1/orders", { 数据: { user_id: userId, items }, }); 返回response.json(); } } **测试中的用法：** test("编辑用户名", async ({ page, request }) => { const api = new TestDataAPI(请求); // 设置：通过 API 创建用户（快速） const 用户 = 等待 api.createUser({ 电子邮件：“edit-test@example.com”， displayName: "编辑前", }); 尝试{ // 测试：通过 UI 编辑 const usersPage = new UsersPage(页面); 等待 usersPage.goto(); // ... 通过 UI 执行编辑 ... }最后{ // 清理：删除测试数据等待 api.deleteUser(user.id); } }); ### 调试不稳定的测试 **1\.使用跟踪查看器查看失败情况：** // playwright.config.ts 使用：{ trace: "on-first-retry", // 仅在重试时捕获跟踪 } 查看跟踪：`npx playwright show-trace trace.zip` **2\.以 head 模式运行进行调试：** npx playwright 测试 --headed --debug 测试/user/create-user.spec.ts **3\.不稳定测试的常见原因：** 原因 |修复 ---|--- 硬编码等待|使用显式等待条件共享测试数据|每个测试都会创建自己的数据动画干扰|在配置中设置“动画：“禁用”” 比赛条件|在断言之前等待 API 响应视口相关行为 |在配置中设置显式视口测试之间的会话泄漏 |正确使用`storageState`，清除cookie **4\.重试策略：** // playwright.config.ts 导出默认的defineConfig({ 重试：process.env.CI？ 2 : 0, // 仅在 CI 中重试 }); ### CI 配置 # .github/workflows/e2e.yml 名称：E2E测试于：推：分支：[主要] 拉请求：分支：[主要] 职位：电子到电子：运行：ubuntu-latest 步骤： - 使用：actions/checkout@v4 - 使用：actions/setup-node@v4 与：节点版本：20 缓存：npm - 名称：安装依赖项运行：npm ci - 名称：安装 Playwright 浏览器运行： npx playwright install --with-deps chromium - 名称：启动应用程序运行：| docker 组成-d npx 等待 http://localhost:3000 --timeout 60000 - 名称：运行 E2E 测试运行：npx 剧作家测试 - 名称：上传测试报告如果：总是（）使用：actions/upload-artifact@v4 与：名称：剧作家报告路径：剧作家报告/ 保留天数：14 - name: 上传失败痕迹如果：失败（）使用：actions/upload-artifact@v4 与：名称：测试痕迹路径：测试结果/ 使用“scripts/run-e2e-with-report.sh”在本地运行 Playwright 并输出 HTML 报告。 ## 示例有关带注释的页面对象类，请参阅“references/page-object-template.ts”。有关带注释的 E2E 测试，请参阅“references/e2e-test-template.ts”。有关生产 Playwright 配置，请参阅“references/playwright-config-example.ts”。

端到端测试

包含技能