novalon-manage-system/docs/reports/E2E_TESTING_GUIDE.md

# E2E测试指南

## 概述

本项目使用Playwright进行端到端（E2E）测试，覆盖关键用户流程和业务场景。

## 技术栈

- **测试框架**: Playwright
- **语言**: TypeScript
- **浏览器**: Chromium
- **模式**: Page Object Model (POM)

## 项目结构

```
novalon-manage-web/e2e/
├── pages/                    # Page Object Model
│   ├── LoginPage.ts          # 登录页面
│   ├── DashboardPage.ts       # 仪表板页面
│   ├── UserManagementPage.ts  # 用户管理页面
│   └── RoleManagementPage.ts  # 角色管理页面
├── fixtures/                 # 测试数据fixtures
│   └── test-data.ts         # 测试数据生成器
├── utils/                    # 工具类
│   └── api-client.ts       # API客户端
├── auth.spec.ts             # 认证测试
├── user-management.spec.ts    # 用户管理测试
├── role-management.spec.ts    # 角色管理测试
├── system-config.spec.ts     # 系统配置测试
├── basic.spec.ts            # 基础功能测试
└── complete-workflow.spec.ts # 完整业务流程测试
```

## 前置条件

1. **启动后端服务**:
   ```bash
   cd novalon-manage-api
   mvn spring-boot:run
   ```

2. **启动前端服务**:
   ```bash
   cd novalon-manage-web
   npm run dev
   ```

3. **确保数据库连接正常**

## 安装依赖

```bash
cd novalon-manage-web
npm install
npx playwright install --with-deps chromium
```

## 运行测试

### 运行所有E2E测试

```bash
cd novalon-manage-web
npx playwright test
```

### 运行特定测试文件

```bash
npx playwright test auth.spec.ts
```

### 运行特定测试用例

```bash
npx playwright test -g "成功登录流程"
```

### 调试模式

```bash
npx playwright test --debug
```

### 有头模式（显示浏览器）

```bash
npx playwright test --headed
```

### 查看测试报告

```bash
npx playwright show-report
```

## 测试覆盖范围

### 1. 认证测试 (auth.spec.ts)
- ✅ 成功登录流程
- ✅ 登录失败 - 无效凭证
- ✅ 登录失败 - 缺少必填字段
- ✅ 登出流程
- ✅ 登录后可以访问所有菜单

### 2. 用户管理测试 (user-management.spec.ts)
- ✅ 创建用户完整流程
- ✅ 编辑用户流程
- ✅ 删除用户流程
- ✅ 搜索用户功能
- ✅ 分页功能
- ✅ 批量删除用户
- ✅ 用户状态切换
- ✅ 导出用户数据

### 3. 角色管理测试 (role-management.spec.ts)
- ✅ 创建角色完整流程
- ✅ 编辑角色流程
- ✅ 分配权限流程
- ✅ 删除角色流程
- ✅ 角色状态切换
- ✅ 搜索角色功能
- ✅ 批量删除角色
- ✅ 复制角色

### 4. 系统配置测试 (system-config.spec.ts)
- ✅ 查看系统配置
- ✅ 编辑系统配置
- ✅ 搜索配置项

### 5. 完整业务流程测试 (complete-workflow.spec.ts)
- ✅ 完整用户管理流程
- ✅ 完整菜单管理流程
- ✅ 完整系统配置流程
- ✅ 完整权限控制流程

### 6. 基础功能测试 (basic.spec.ts)
- ✅ 首页加载测试
- ✅ 登录页面访问测试
- ✅ 后端健康检查
- ✅ 数据库连接检查
- ✅ 前端页面可访问性
- ✅ API代理配置验证

## Page Object Model

### LoginPage

```typescript
import { LoginPage } from './pages/LoginPage';

const loginPage = new LoginPage(page);
await loginPage.goto();
await loginPage.login('admin', 'admin123');
```

### DashboardPage

```typescript
import { DashboardPage } from './pages/DashboardPage';

const dashboardPage = new DashboardPage(page);
await dashboardPage.navigateToUserManagement();
```

### UserManagementPage

```typescript
import { UserManagementPage } from './pages/UserManagementPage';

const userPage = new UserManagementPage(page);
await userPage.clickCreateUser();
await userPage.fillUserForm(userData);
await userPage.submitForm();
```

### RoleManagementPage

```typescript
import { RoleManagementPage } from './pages/RoleManagementPage';

const rolePage = new RoleManagementPage(page);
await rolePage.clickCreateRole();
await rolePage.fillRoleForm(roleData);
await rolePage.submitForm();
```

## 测试数据Fixtures

### 使用预定义测试数据

```typescript
import { test } from './fixtures/test-data';

test('使用admin用户', async ({ adminUser }) => {
  console.log(adminUser.username); // 'admin'
  console.log(adminUser.password); // 'admin123'
});
```

### 动态生成测试数据

```typescript
import { test } from './fixtures/test-data';

test('生成测试用户', async ({ generateTestUser }) => {
  const user = generateTestUser();
  console.log(user.username); // 'testuser_1234567890'
  console.log(user.email); // 'test_1234567890@example.com'
});
```

## CI/CD集成

E2E测试已集成到Woodpecker CI流水线中：

```yaml
frontend-e2e-test:
  image: mcr.microsoft.com/playwright:v1.42.0-jammy
  commands:
    - cd novalon-manage-web
    - npm ci
    - npx playwright install --with-deps chromium
    - npx playwright test
  environment:
    NODE_ENV: test
    CI: true
  depends_on:
    - deploy-staging
  when:
    - event: pull_request
```

## 最佳实践

### 1. 使用Page Object Model
- 将页面逻辑封装在Page类中
- 避免在测试文件中直接操作DOM元素
- 提高测试可维护性

### 2. 使用稳定的定位器
```typescript
// ❌ 不推荐：使用CSS类名
await page.click('.btn-primary');

// ✅ 推荐：使用角色定位器
await page.getByRole('button', { name: '提交' }).click();

// ✅ 推荐：使用data-testid
await page.getByTestId('submit-button').click();
```

### 3. 等待策略
```typescript
// ❌ 不推荐：固定等待
await page.waitForTimeout(3000);

// ✅ 推荐：等待特定条件
await expect(page.locator('.success-message')).toBeVisible();
```

### 4. 测试独立性
- 每个测试应该独立运行
- 不要依赖其他测试的执行顺序
- 使用beforeEach/afterEach进行设置和清理

### 5. 使用test.step提高可读性
```typescript
await test.step('1. 登录系统', async () => {
  await loginPage.login('admin', 'admin123');
});

await test.step('2. 创建用户', async () => {
  await userPage.clickCreateUser();
  // ...
});
```

## 调试技巧

### 1. 使用调试模式
```bash
npx playwright test --debug
```

### 2. 使用有头模式
```bash
npx playwright test --headed
```

### 3. 查看trace文件
```bash
npx playwright show-trace trace.zip
```

### 4. 截图和视频
Playwright会在测试失败时自动截图和录制视频，存储在：
- `test-results/` 目录

## 故障排除

### 问题1：浏览器启动失败
```bash
npx playwright install --with-deps chromium
```

### 问题2：连接超时
检查后端服务是否正常运行：
```bash
curl http://localhost:8084/actuator/health
```

### 问题3：元素定位失败
使用Playwright Inspector检查元素：
```bash
npx playwright codegen http://localhost:3003
```

## 测试报告

测试执行后会生成以下报告：

1. **HTML报告**: `playwright-report/index.html`
2. **JUnit报告**: `test-results/junit.xml`
3. **Trace文件**: `test-results/trace.zip` (失败时)

## 贡献指南

添加新的E2E测试：

1. 在`pages/`目录创建对应的Page类
2. 在`e2e/`目录创建测试文件
3. 使用Page Object Model编写测试
4. 确保测试独立性和可重复性
5. 添加适当的断言和验证

## 参考资料

- [Playwright官方文档](https://playwright.dev/)
- [Page Object Model最佳实践](https://playwright.dev/docs/pom)
- [测试最佳实践](https://playwright.dev/docs/best-practices)