generate

生成 Playwright 测试

根据用户故事、URL、组件名称或功能描述，生成可用于生产环境的 Playwright 测试。

输入

$ARGUMENTS 包含需要测试的内容。示例：

• "user can log in with email and password"
• "the checkout flow"
• "src/components/UserProfile.tsx"
• "the search page with filters"

步骤

1. 理解测试目标

解析 $ARGUMENTS，确定以下内容：

• 用户故事：提取需要验证的行为
• 组件路径：读取组件源代码
• 页面/URL：确定路由及其元素
• 功能名称：映射到相关的应用区域

2. 探索代码库

使用 Explore 子 Agent 收集上下文：

• 读取 playwright.config.ts 中的 testDir、baseURL、projects
• 检查 testDir 中已有的测试，了解模式、fixtures 和约定
• 如果提供了组件路径，读取该组件，了解其 props、状态和交互
• 检查 pages/ 中是否已有页面对象
• 检查 fixtures/ 中是否已有 fixtures
• 检查认证设置（auth.setup.ts 或 storageState 配置）

3. 选择模板

检查本插件中的 templates/，查找匹配的模式：

测试内容……	模板加载位置
登录/认证流程	../pw/templates/auth/login.md
CRUD 操作	templates/crud/
结账/支付	templates/checkout/
搜索/筛选 UI	templates/search/
表单提交	templates/forms/
仪表板/数据	templates/dashboard/
设置页面	templates/settings/
新手引导流程	templates/onboarding/
API 端点	templates/api/
无障碍	templates/accessibility/

将模板适配到具体应用——将 {{placeholders}} 替换为实际的选择器、URL 和数据。

4. 生成测试

遵循以下规则：

结构：

import { test, expect } from '@playwright/test';
// Import custom fixtures if the project uses them

test.describe('Feature Name', () => {
  // Group related behaviors

  test('should <expected behavior>', async ({ page }) => {
    // Arrange: navigate, set up state
    // Act: perform user action
    // Assert: verify outcome
  });
});

定位器优先级（使用第一个可行的）：

1. getByRole() —— 按钮、链接、标题、表单元素
2. getByLabel() —— 带标签的表单字段
3. getByText() —— 非交互式文本内容
4. getByPlaceholder() —— 带占位文本的输入框
5. getByTestId() —— 当语义化选项不可用时

断言 —— 始终使用 web-first 断言：

// GOOD — auto-retries
await expect(page.getByRole('heading')).toBeVisible();
await expect(page.getByRole('alert')).toHaveText('Success');

// BAD — no retry
const text = await page.textContent('.msg');
expect(text).toBe('Success');

禁止使用：

• page.waitForTimeout()
• page.$(selector) 或 page.$$(selector)
• 除非绝对必要，否则不使用裸 CSS 选择器
• 能用定位器完成的事情，不使用 page.evaluate()

必须包含：

• 能说明行为的描述性测试名称
• 与正常流程并列的错误/边界情况测试
• 每个 Playwright 调用前都要正确使用 await
• 基于 baseURL 的相对导航（使用 page.goto('/')，而不是 page.goto('http://...')）

5. 匹配项目约定

• 如果项目使用 TypeScript → 生成 .spec.ts
• 如果项目使用 JavaScript → 生成使用 require() 导入的 .spec.js
• 如果项目有页面对象 → 使用它们，而不是内联定位器
• 如果项目有自定义 fixtures → 导入并使用它们
• 如果项目有测试数据目录 → 在该目录中创建测试数据文件

6. 生成辅助文件（如需要）

• 页面对象：如果测试涉及同一页面上的 5 个及以上唯一定位器，则创建页面对象
• Fixture：如果测试需要共享的前置设置（认证、数据），则创建或扩展 fixture
• 测试数据：如果测试使用结构化数据，则在 test-data/ 中创建 JSON 文件

7. 验证

运行生成的测试：

npx playwright test <generated-file> --reporter=list

如果失败：

1. 阅读错误信息
2. 修复测试（而不是应用）
3. 重新运行
4. 如果是应用问题，向用户报告

输出

• 生成的测试文件及其路径
• 创建的辅助文件（页面对象、fixtures、数据）
• 测试运行结果
• 覆盖说明：现在已测试了哪些行为