E2E 测试文档

基于 Playwright 的端到端测试，用于验证关键功能修复后没有回归。

环境准备

首次使用需要安装浏览器驱动（已安装则跳过）：

npx playwright install chromium

运行测试

所有命令需要传入测试账号环境变量。

运行全部测试：

TEST_PHONE=15223307018 TEST_PASSWORD=xxx npm run test:e2e

只运行某个测试文件：

TEST_PHONE=15223307018 TEST_PASSWORD=xxx npx playwright test e2e/tests/cancel-api.spec.ts

带 UI 界面（可视化调试）：

TEST_PHONE=15223307018 TEST_PASSWORD=xxx npm run test:e2e:ui

查看上次运行的 HTML 报告：

npm run test:e2e:report

目录结构

e2e/
├── .auth/               # 登录状态缓存（git ignored，自动生成）
├── .env.test.example    # 测试账号模板
├── setup/
│   └── auth.setup.ts    # 登录初始化（保存 localStorage 登录态）
└── tests/
    ├── cancel-api.spec.ts   # 深度检索历史切换不触发 cancel 请求
    ├── file-upload.spec.ts  # 文件上传 100MB 大小限制
    └── welcome-ui.spec.ts   # Welcome 页面 UI 入口验证

当前测试用例

cancel-api.spec.ts ✅

验证 Bug 修复：在 Welcome 页面切换深度检索历史记录时，不应触发 POST /cancel 请求。

• 切换深度检索历史记录时不应触发 /cancel 请求 — 核心回归测试
• 进行中的深度检索点击终止按钮应正常触发 /cancel — 正向路径验证

file-upload.spec.ts

验证 AgentPanel 文件上传超过 100MB 时显示错误提示。

注意：AgentPanel 需要特定 URL 参数才会显示，测试依赖具体页面状态。

welcome-ui.spec.ts ✅

验证 Welcome 页面 UI 结构：

• AI 模式选择器（快速问答 / 深度检索）正常显示
• 模式切换功能正常
• 问题建议列表显示正确

工作原理

1. setup 阶段：自动登录并将 localStorage（含 token）保存到 e2e/.auth/state.json
2. 测试阶段：复用保存的登录状态，直接进入已登录页面
3. 网络拦截：通过 page.on('request', ...) 监听 API 请求，验证非预期请求没有被触发

新增测试指引

在 e2e/tests/ 下新建 xxx.spec.ts，参考以下模板：

import { test, expect } from "@playwright/test";

test.describe("功能名称", () => {
  test("测试描述", async ({ page }) => {
    // 收集特定 API 请求（可选）
    const targetRequests: string[] = [];
    page.on("request", (req) => {
      if (req.url().includes("/your-api")) targetRequests.push(req.url());
    });

    await page.goto("/#/app/welcome");
    await page.waitForLoadState("domcontentloaded");
    await page.waitForSelector(".ai-mode-selector");

    // 操作 + 断言
    await expect(page.locator(".some-element")).toBeVisible();
  });
});

关键注意事项：

• 使用 waitForLoadState("domcontentloaded") 而不是 "networkidle"（应用有持久 SSE 连接，永远不会 idle）
• 等待具体元素出现代替固定 waitForTimeout