# Playwright MCP 测试执行指南

## 🎯 使用说明

本指南将指导您在 Cursor 中使用 Playwright MCP 插件执行维修分类功能的完整测试。

## 📋 前置准备

### 1. 环境检查

```bash
✅ 系统运行状态确认
- 前端服务: http://localhost:80 (正常运行)
- 后端服务: http://localhost:8080 (正常运行)
- 数据库服务: 正常连接

✅ 测试账号准备
- 用户名: admin
- 密码: admin123
- 权限: 具备维修分类管理的完整权限
```

### 2. Cursor 环境准备

```bash
✅ Cursor 编辑器已安装最新版本
✅ Playwright MCP 插件已安装并启用
✅ 项目已在 Cursor 中打开
```

## 🚀 测试执行步骤

### 方式一：通过 Playwright MCP 直接执行

1. **打开测试脚本**

    ```
    在 Cursor 中打开文件:
    docs/测试文档/后勤管理/物业管理/维修分类/playwright-scripts/maintenance-category-e2e.js
    ```

2. **启动 Playwright MCP**

    - 在 Cursor 中按 `Ctrl+Shift+P` (Windows/Linux) 或 `Cmd+Shift+P` (Mac)
    - 输入 "Playwright" 并选择相关命令
    - 选择 "Run Playwright Test" 或类似选项

3. **配置浏览器设置**

    - 选择浏览器: Chrome/Chromium (推荐)
    - 模式: Headed (可视化模式，便于观察测试过程)
    - 窗口大小: 1920x1080 (推荐)

4. **开始执行测试**
    - 点击"开始测试"或"Run"按钮
    - 观察浏览器自动化执行过程
    - 等待测试完成

### 方式二：通过 Cursor 聊天界面执行

1. **打开 Cursor 聊天**

    - 在 Cursor 中打开 AI 聊天界面
    - 确保 Playwright MCP 插件已连接

2. **发送测试命令**

    ```
    请使用 Playwright MCP 执行维修分类功能测试：

    1. 导航到维修分类页面 http://localhost:80/hq/pm/repairCategory
    2. 执行完整的 CRUD 操作测试
    3. 验证树形结构功能
    4. 测试搜索和过滤功能
    5. 检查数据验证规则
    6. 生成详细的测试报告
    ```

3. **观察执行过程**
    - AI 将自动控制浏览器执行测试
    - 每个步骤都会有详细的执行日志
    - 关键操作会自动截图记录

## 🧪 测试执行流程

### 阶段 1: 环境准备 (约 3 分钟)

```javascript
✅ 浏览器启动和初始化
✅ 导航到登录页面
✅ 执行用户登录
✅ 验证登录成功
✅ 导航到维修分类页面
```

### 阶段 2: 页面验证 (约 2 分钟)

```javascript
✅ 验证页面标题和结构
✅ 检查关键UI元素存在
✅ 验证数据表格加载
✅ 检查操作按钮可用性
```

### 阶段 3: CRUD 操作测试 (约 15 分钟)

```javascript
✅ 新增维修分类
  - 填写完整表单信息
  - 提交并验证结果
  - 确认数据保存成功

✅ 查询分类信息
  - 搜索新建分类
  - 验证搜索结果准确性
  - 重置搜索条件

✅ 编辑分类信息
  - 修改分类属性
  - 保存修改
  - 验证更新结果

✅ 删除分类(清理阶段执行)
  - 确认删除操作
  - 验证数据移除
```

### 阶段 4: 树形结构测试 (约 10 分钟)

```javascript
✅ 创建父级分类
✅ 创建子级分类
✅ 验证父子关系
✅ 测试树形展示
✅ 检查展开/折叠功能
```

### 阶段 5: 搜索功能测试 (约 8 分钟)

```javascript
✅ 按名称搜索测试
✅ 按编码搜索测试
✅ 按状态过滤测试
✅ 组合条件搜索测试
✅ 搜索结果验证
```

### 阶段 6: 数据验证测试 (约 5 分钟)

```javascript
✅ 必填字段验证
✅ 数据格式验证
✅ 边界值测试
✅ 错误提示验证
```

### 阶段 7: 清理工作 (约 2 分钟)

```javascript
✅ 删除测试数据
✅ 恢复初始状态
✅ 生成测试报告
```

## 📊 测试结果查看

### 实时监控

-   **控制台日志**: 查看每个步骤的执行状态
-   **浏览器窗口**: 观察实际操作过程
-   **截图记录**: 关键步骤的自动截图

### 测试报告

-   **执行概要**: 总体测试结果统计
-   **详细日志**: 每个测试用例的执行详情
-   **问题记录**: 发现的 bug 和异常情况
-   **性能数据**: 页面加载和操作响应时间

## 🔧 常见问题处理

### 问题 1: 登录失败

```bash
症状: 无法正常登录系统
原因: 用户名密码错误或系统未启动
解决:
  1. 确认系统服务正常运行
  2. 检查用户名密码是否正确
  3. 确认用户账号是否激活
```

### 问题 2: 页面元素定位失败

```bash
症状: 无法找到指定的UI元素
原因: 页面结构变化或加载未完成
解决:
  1. 增加等待时间
  2. 更新元素选择器
  3. 检查页面是否正确加载
```

### 问题 3: 测试数据冲突

```bash
症状: 创建数据时提示重复或冲突
原因: 之前的测试数据未清理
解决:
  1. 手动清理测试数据
  2. 修改测试数据值
  3. 执行数据清理脚本
```

### 问题 4: 权限不足

```bash
症状: 某些操作被拒绝或按钮不可见
原因: 当前用户权限不足
解决:
  1. 使用管理员账号登录
  2. 检查角色权限配置
  3. 联系系统管理员
```

## 🎯 测试成功标准

### 功能性验证

-   ✅ 所有 CRUD 操作正常执行
-   ✅ 数据验证规则正确生效
-   ✅ 搜索过滤功能准确有效
-   ✅ 树形结构正确展示

### 易用性验证

-   ✅ 用户界面响应流畅
-   ✅ 操作提示清晰准确
-   ✅ 错误处理合理有效
-   ✅ 交互流程符合预期

### 性能验证

-   ✅ 页面加载时间 < 3 秒
-   ✅ 操作响应时间 < 2 秒
-   ✅ 搜索响应时间 < 1 秒
-   ✅ 无明显卡顿现象

## 📝 测试记录模板

### 执行记录

```markdown
**测试执行时间**: 2025-07-01 HH:mm:ss
**执行环境**:

-   操作系统: [Windows/Mac/Linux]
-   浏览器: Chrome/Edge 版本号
-   系统版本: [前端/后端版本]

**测试结果**:

-   总测试用例: 9 个
-   通过用例: \_个
-   失败用例: \_个
-   跳过用例: \_个

**发现问题**:

1. [问题描述]
2. [问题描述]

**改进建议**:

1. [建议内容]
2. [建议内容]
```

## 🔄 持续集成建议

### 定期执行

-   **每日构建**: 自动执行基础功能测试
-   **版本发布前**: 执行完整回归测试
-   **功能更新后**: 针对性功能测试

### 自动化监控

-   **测试结果通知**: 自动发送测试报告
-   **性能监控**: 跟踪性能指标变化
-   **问题跟踪**: 自动创建 bug 记录

---

**文档维护**: 测试过程中发现的问题请及时更新到此文档  
**技术支持**: 如遇到技术问题，请参考项目开发文档或联系开发团队  
**文档版本**: v1.0  
**最后更新**: 2025-07-01