---
name: tevin-write-e2etest
description: 为项目编写 Playwright E2E 测试脚本的技能。适用于实现组件或功能的端到端测试，避免使用 MCP，改用传统的测试脚本方式。
license: MIT
compatibility: 项目使用 @playwright/test、React、Vite、TypeScript
metadata:
author: tevin

version: "1.0"

使用 @playwright/test 编写 E2E 测试，不使用 MCP。

项目测试规范

测试目录: test/e2e/
路由模式: hash 路由，#/preview/pages/<path>
开发服务器: pnpm dev (http://localhost:5173)

测试文件结构

import { test, expect } from '@playwright/test';

test.describe('功能名称', () => {
  test.beforeEach(async ({ page }) => {
    // 访问包含该功能的页面
    await page.goto('http://localhost:5173/#/preview/pages/xxx/Page.tsx');
  });

  test('测试场景描述', async ({ page }) => {
    // 使用 page.waitForSelector 或 expect 等待元素
    await expect(page.locator('text=预期文本')).toBeVisible();
  });

  test('交互功能测试', async ({ page }) => {
    // 点击操作
    await page.click('text=可点击文本');
    // 验证结果
    await expect(page.locator('text=结果文本')).toBeVisible();
  });
});

编写步骤

1. 确认测试页面路径

• 组件示例页面: http://localhost:5173/#/preview/pages/<component>/<Page>.tsx
• 如果不确定，先运行 pnpm dev 访问确认

1. 分析页面功能

• 识别页面的主要元素（菜单、表单、按钮等）
• 确定需要测试的用户交互流程

1. 编写测试用例

• 每个 test 块描述一个独立场景
• 使用 test.beforeEach 统一初始化
• 用 expect 断言而非 console.log 验证

1. 运行测试

• 确保开发服务器已启动: pnpm dev
• 运行测试: pnpm exec playwright test test/e2e/<spec>.ts

最佳实践

• 使用稳定选择器: 优先使用 text= 定位文本，避免脆弱的 CSS 选择器
• 显式等待: 使用 expect(locator).toBeVisible() 而非 page.waitForTimeout()
• 独立测试: 每个测试应能独立运行，不依赖其他测试的状态
• 清晰命名: 测试名称应描述预期行为，如 should display menu items

常见模式

菜单导航测试:
typescript test('菜单点击跳转', async ({ page }) => { await page.click('text=菜单项'); await expect(page.locator('text=目标页面内容')).toBeVisible(); });

表单输入测试:
typescript test('表单提交', async ({ page }) => { await page.fill('input[placeholder="输入框"]', '测试值'); await page.click('button:has-text("提交")'); await expect(page.locator('text=成功消息')).toBeVisible(); });

注意事项

• 不要使用 Playwright MCP (@playwright/mcp 已从项目移除)
• 测试文件后缀为 .spec.ts
• 首次运行需要安装浏览器: pnpm exec playwright install