base/frontend/react-shadcn/pc/tests/EXECUTION_GUIDE.md

Playwright MCP 测试执行手册

🚀 快速开始

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

在 Claude 中直接说：

"执行全部 Playwright 测试"

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

方式二：分模块执行

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

方式三：使用 npm 脚本

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

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

📋 前置准备

1. 检查服务状态

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

预期输出：

🔍 检查服务状态...

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

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

2. 手动启动服务

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

后端：

cd backend
go run base.go -f etc/base-api.yaml

前端：

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个测试用例

🎯 测试执行命令参考

执行所有测试

// 在 Claude 中执行
import { runAllTests } from './tests/index';
await runAllTests();

执行单个模块

import { testSuite } from './tests/index';
import { runTestModule } from './tests/utils';

await runTestModule(testSuite.login);

带过滤条件执行

await runAllTests({ filter: '登录' });

📊 测试报告

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

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

🔧 配置说明

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

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. 运行测试验证

示例：

// tests/new-feature.test.ts
import type { TestModule } from './types';

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