在 Cursor 环境中基于多个前后端项目使用 Playwright 进行整体测试

## 一、为什么需要整体测试

在现代 Web 开发中，一个完整的业务系统往往由多个前后端项目组成：前端可能包含用户端 SPA、管理后台、移动端 H5；后端则可能拆分为 API 网关、业务服务、数据服务等微服务。单独对某个项目进行单元测试或集成测试，无法覆盖跨服务的交互场景。

端到端（E2E）整体测试的目标是**模拟真实用户操作**，验证从前端页面到后端数据库的完整链路是否正常工作。Playwright 作为微软推出的现代浏览器自动化框架，天然适合这一场景。

## 二、Playwright 的核心优势

相比 Selenium、Cypress 等传统方案，Playwright 具备以下优势：

- **多浏览器支持**：Chromium、Firefox、WebKit 三大引擎，一套代码覆盖主流浏览器
- **自动等待机制**：内置智能等待，告别 sleep 和 flaky test
- **网络拦截**：可以 mock API 响应、拦截请求，灵活控制测试环境
- **多页面与多标签**：原生支持多 tab、iframe、弹窗等复杂场景
- **Trace Viewer**：录制操作轨迹，调试失败用例时可回放每一步操作的截图和网络请求
- **API 测试**：不仅能测 UI，还能直接发起 HTTP 请求验证接口

## 三、Cursor IDE 中的测试工作流

Cursor 作为 AI 驱动的代码编辑器，与 Playwright 结合后能显著提升测试效率：

### 3.1 AI 辅助生成测试用例

在 Cursor 中，可以通过 Agent 模式直接描述测试意图，让 AI 自动生成 Playwright 测试脚本。例如：

```
// 只需描述：「测试用户登录后创建文章并验证文章列表中出现新文章」
// Cursor Agent 会自动生成完整的 Playwright 脚本，包括：
// - 登录流程
// - 表单填写
// - 提交验证
// - 数据清理
```

### 3.2 命令自动放行

在 Cursor Settings 中配置 Agent 的命令放行列表（Command Allowlist），将node添加进去后，Agent 执行测试脚本时无需手动确认，实现真正的自动化闭环。

### 3.3 实时调试与截图

Playwright 支持在测试过程中截取页面截图，结合 Cursor 的文件预览功能，可以直接在编辑器中查看测试结果的可视化反馈。

## 四、多项目整体测试架构设计

对于包含多个前后端服务的项目，建议采用以下测试架构：

### 4.1 目录结构

### 4.2 跨服务测试编排

关键在于**测试数据的准备与清理**。推荐使用 Playwright 的 fixture 机制：

```
// fixtures/auth.ts
import { test as base } from '@playwright/test';

export const test = base.extend({
  adminPage: async ({ browser }, use) => {
    const context = await browser.newContext();
    const page = await context.newPage();
    // 登录管理后台
    await page.goto('http://localhost:8080/admin/login');
    await page.fill('#username', process.env.ADMIN_USER);
    await page.fill('#password', process.env.ADMIN_PASS);
    await page.click('button[type="submit"]');
    await page.waitForURL('**/admin/home');
    await use(page);
    await context.close();
  },
  userPage: async ({ browser }, use) => {
    const context = await browser.newContext();
    const page = await context.newPage();
    // 前台用户页面
    await page.goto('http://localhost:3000');
    await use(page);
    await context.close();
  }
});
```

### 4.3 跨服务场景示例

典型的跨服务测试场景：在管理后台发布文章，然后验证前台用户能看到：

```
test('管理员发布文章后前台可见', async ({ adminPage, userPage }) => {
  // Step 1: 管理员在后台创建文章
  await adminPage.goto('/admin/posts');
  await adminPage.click('text=新建文章');
  await adminPage.fill('#form-title', '测试文章标题');
  await adminPage.fill('#editor', '测试文章内容...');
  await adminPage.click('#btn-save');
  await expect(adminPage.locator('.toast-success')).toBeVisible();

// Step 2: 前台用户刷新首页验证
  await userPage.reload();
  await expect(userPage.locator('text=测试文章标题')).toBeVisible();
});
```

## 五、持续集成中的最佳实践

### 5.1 并行执行

Playwright 原生支持并行测试，在playwright.config.ts中配置：

```
export default defineConfig({
  workers: process.env.CI ? 2 : undefined,
  retries: process.env.CI ? 2 : 0,
  use: {
    trace: 'on-first-retry',  // 失败重试时录制 trace
    screenshot: 'only-on-failure',
  },
});
```

### 5.2 环境隔离

每次 CI 运行时，通过 Docker Compose 拉起完整的服务栈（前端 + 后端 + 数据库），确保测试环境的一致性和隔离性：

```
# docker-compose.test.yml
services:
  backend:
    build: ./backend
    environment:
      - DB_HOST=test-db
  frontend:
    build: ./frontend
    depends_on: [backend]
  test-db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: test_blog
```

### 5.3 测试报告

Playwright 内置 HTML Reporter，生成美观的测试报告：

```
npx playwright test --reporter=html
npx playwright show-report
```

## 六、常见问题与解决方案

| 问题 | 解决方案 |
| --- | --- |
| 测试不稳定（Flaky） | 使用 Playwright 内置的 auto-wait，避免硬编码 sleep；利用expect的重试机制 |
| 跨域问题 | 在测试配置中设置ignoreHTTPSErrors: true，或通过代理统一入口 |
| 数据残留 | 使用 fixture 的 teardown 阶段清理测试数据；或每次测试前重置数据库 |
| CI 环境无头浏览器报错 | 确保安装了系统依赖：npx playwright install-deps |
| 多服务启动顺序 | 使用webServer配置或 Docker 的depends_on+ healthcheck |

## 七、总结

在 Cursor + Playwright 的组合下，多项目整体测试变得高效且可维护：

1. **AI 驱动**：Cursor Agent 可以根据需求描述自动生成测试脚本，大幅降低编写成本
2. **跨服务覆盖**：Playwright 的多页面能力天然支持前后端联动测试
3. **可视化调试**：Trace Viewer 和截图功能让失败排查变得直观
4. **CI 友好**：并行执行、自动重试、Docker 隔离，轻松集成到持续集成流水线

随着 AI 编程工具的不断进化，「描述需求 - 生成测试 - 自动执行 - 反馈修复」的闭环将越来越成熟，测试不再是开发的负担，而是质量保障的利器。

评论