# Playwright MCP 测试执行手册

## 🚀 快速开始

### 方式一：一键执行（推荐）

在 Claude 中直接说：

> **"执行全部 Playwright 测试"**

Claude 会自动执行 `tests/index.ts` 中定义的所有测试模块。

### 方式二：分模块执行

> **"执行登录测试"**
> **"执行用户管理测试"**

### 方式三：使用 npm 脚本

```bash
# 检查服务状态
npm run test:check

# 启动测试环境（自动启动前后端服务）
npm run test:e2e
```

## 📋 前置准备

### 1. 检查服务状态

```bash
cd frontend/react-shadcn/pc
node tests/check-services.js
```

预期输出：
```
🔍 检查服务状态...

✅ 后端服务: http://localhost:8888/api/v1 (401)
✅ 前端服务: http://localhost:5175/ (200)

✅ 所有服务正常运行，可以执行测试
```

### 2. 手动启动服务

如果服务未启动，请运行：

**后端：**
```bash
cd backend
go run base.go -f etc/base-api.yaml
```

**前端：**
```bash
cd frontend/react-shadcn/pc
npm run dev
```

## 🧪 测试模块说明

| 模块 | 文件 | 测试数量 | 说明 |
|------|------|----------|------|
| 登录测试 | `login.test.ts` | 4个 | 登录页面功能验证 |
| 仪表板测试 | `dashboard.test.ts` | 4个 | 统计数据和图表展示 |
| 用户管理测试 | `users.test.ts` | 6个 | 用户CRUD操作 |
| 设置页面测试 | `settings.test.ts` | 5个 | 设置分类和开关控件 |
| 导航测试 | `navigation.test.ts` | 4个 | 路由保护和导航功能 |

**总计：23个测试用例**

## 🎯 测试执行命令参考

### 执行所有测试
```typescript
// 在 Claude 中执行
import { runAllTests } from './tests/index';
await runAllTests();
```

### 执行单个模块
```typescript
import { testSuite } from './tests/index';
import { runTestModule } from './tests/utils';

await runTestModule(testSuite.login);
```

### 带过滤条件执行
```typescript
await runAllTests({ filter: '登录' });
```

## 📊 测试报告

执行完成后，Claude 会生成测试报告：

```
═══════════════════════════════════════════════════════════
📊 测试报告摘要
═══════════════════════════════════════════════════════════
   总计: 23 个测试
   ✅ 通过: 23 个
   ❌ 失败: 0 个
   ⏱️  耗时: 45.23 秒
═══════════════════════════════════════════════════════════
```

## 🔧 配置说明

测试配置位于 `tests/config.ts`：

```typescript
export const TEST_CONFIG = {
  baseURL: 'http://localhost:5175',  // 前端地址
  apiURL: 'http://localhost:8888/api/v1',  // 后端API地址
  testUser: {
    email: 'admin@example.com',
    password: 'password123',
  },
};
```

## ❗ 常见问题

### 1. 页面加载超时
```
检查：
- npm run test:check
- 前端是否运行在 http://localhost:5175
```

### 2. 登录失败
```
检查：
- 后端是否运行在 http://localhost:8888
- API 地址是否正确
- 测试用户是否存在
```

### 3. MCP 工具未找到
```
检查 Claude Code 设置：
- Settings > MCP Servers > Playwright 是否已启用
```

## 📁 文件结构

```
tests/
├── index.ts              # 测试入口和套件定义
├── config.ts             # 测试配置和选择器
├── login.test.ts         # 登录测试
├── dashboard.test.ts     # 仪表板测试
├── users.test.ts         # 用户管理测试
├── settings.test.ts      # 设置页面测试
├── navigation.test.ts    # 导航和路由保护测试
├── runner.ts             # 测试运行器
├── check-services.js     # 服务状态检查
├── run-tests.bat         # Windows 一键启动脚本
└── EXECUTION_GUIDE.md    # 本手册
```

## 📝 新增测试

如需新增测试模块：

1. 在 `tests/` 目录创建 `.test.ts` 文件
2. 实现 `TestModule` 接口
3. 在 `tests/index.ts` 中注册
4. 运行测试验证

示例：
```typescript
// tests/new-feature.test.ts
import type { TestModule } from './types';

export const newFeatureTest: TestModule = {
  name: '新功能测试',
  description: '验证新功能工作正常',
  tests: [
    {
      name: '测试用例1',
      run: async () => {
        // 测试逻辑
      }
    }
  ]
};
```