feat: E2E 测试集成真实后端

- Playwright 双 webServer 模式自动启动 Go 后端 + Vite 前端 - 后端使用临时 SQLite 数据库隔离，固定端口 19026 - vite.config.ts proxy target 动态读取环境变量 - 新增 sql.js 依赖用于 SQLite 统计数据 seed - 新增 e2e/fixtures.ts 共享工具模块（API seed + SQLite seed） - 拆分测试文件 5→7（providers/models/stats/navigation/validation） - 删除旧文件 crud.spec.ts/sidebar.spec.ts/stats-cards.spec.ts - E2E 测试尚有部分用例需调试修复
2026-04-22 00:31:35 +08:00
parent 4fc5fb4764
commit 59179094ed
20 changed files with 973 additions and 540 deletions
--- a/openspec/changes/e2e-real-backend/.openspec.yaml
+++ b/openspec/changes/e2e-real-backend/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-21
--- a/openspec/changes/e2e-real-backend/design.md
+++ b/openspec/changes/e2e-real-backend/design.md
@@ -0,0 +1,85 @@
+## Context
+
+前端 Playwright E2E 测试当前只启动 `bun run dev`（Vite dev server），后端不参与。现有 5 个 E2E 测试文件中，所有写操作（创建/编辑/删除供应商和模型）的验证都不完整——因为 API 请求无法到达后端，表单提交后的数据持久化无法验证，大量测试在缺少已有数据时直接 `test.skip()`。
+
+后端具备天然测试友好特性：Go CLI 参数可覆盖所有配置（`--server-port`、`--database-path`、`--log-path`、`--log-level`），SQLite 文件数据库使每次测试可用独立临时文件，首次启动自动运行 goose 迁移，有 `/health` 端点可供就绪检查。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- `bun run test:e2e` 一条命令自动启动隔离后端 + 前端，运行完整 E2E 测试，自动清理
+- 每次测试运行使用干净的临时数据库，测试间无状态污染
+- E2E 测试能验证完整 CRUD 流程：创建→验证存在→编辑→验证更新→删除→验证消失
+- 统计页面可通过 seed 数据验证数字、筛选、图表渲染
+- 对日常开发流程零侵入（`bun run dev` 行为不变）
+- Windows 原生兼容（项目在 Windows 上开发）
+
+**Non-Goals:**
+
+- 不修改后端代码（仅通过 CLI 参数启动现有二进制）
+- 不引入 CI 流水线配置
+- 不改动 MSW 在单元测试中的使用
+- 不实现随机端口分配（使用固定非默认端口 19026）
+- 不引入 cross-env 等跨平台环境变量工具
+
+## Decisions
+
+### Decision 1: 固定测试端口 19026 vs 随机端口
+
+**选择**: 固定端口 19026
+
+**理由**: 随机端口需要在 `globalSetup` 中 spawn 后端进程、等待健康检查、管理进程生命周期（包括 Windows 上的 SIGTERM 问题），复杂度高。19026 是非标准端口，与开发端口 9826 不冲突，冲突概率极低。Playwright `webServer` 数组模式可直接管理两个进程的生命周期，无需手动 spawn/kill。
+
+**备选方案**: `globalSetup` 中分配随机端口 → spawn 后端 → 等待健康检查 → `globalTeardown` 中 kill 进程。在 Windows 上 SIGTERM 不可靠，需 taskkill 强杀，进程管理复杂。
+
+### Decision 2: 环境变量传递方式
+
+**选择**: `process.env` 继承，不引入 cross-env
+
+**理由**: Playwright 的 `webServer` 通过 `child_process.spawn` 启动子进程，子进程默认继承父进程 `process.env`。在 `playwright.config.ts` 模块顶层设置 `process.env.NEX_BACKEND_PORT = '19026'`，Vite dev server 子进程自动继承，`vite.config.ts` 中 `defineConfig` 函数可读取。E2E 测试文件与 config 同进程，直接读取即可。三处消费者（后端 CLI flags / Vite / 测试文件）都无需额外工具。
+
+### Decision 3: 统计数据 seed 方式
+
+**选择**: sql.js 直接操作 SQLite 文件
+
+**理由**: 统计数据（`usage_stats` 表）只能通过后端 `statsService.Record()` 按当天日期 upsert，没有 API 可以插入任意日期的历史数据。统计页面测试需要多日趋势数据来验证筛选和图表。sql.js 是纯 WASM 实现，无原生编译依赖，Windows 上零风险。通过"读文件→内存操作→写回"模式在 `beforeAll` 中 seed 数据，串行化保证无并发冲突。
+
+**备选方案**:
+- better-sqlite3：需要原生编译，Windows 上可能有编译工具链问题
+- 后端加测试专用 seed API：需要修改后端代码，违反"不改后端"原则
+- 只测今日数据：无法验证日期筛选和趋势图表，测试覆盖不足
+
+### Decision 4: 临时文件管理
+
+**选择**: `fs.mkdtempSync(os.tmpdir() + '/nex-e2e-')` 创建，`fs.rm(dir, { recursive: true, force: true })` 在 `globalTeardown` 清理
+
+**理由**: `mkdtempSync` 跨平台安全，Windows 上生成 `%TEMP%\nex-e2e-xxxxxxxx` 路径。Go 后端的 `--database-path` 和 `--log-path` 参数接受 Windows 路径。`fs.rm` 是 Node.js 14.14+ 内置的递归删除 API，无需额外依赖（rimraf 等）。
+
+### Decision 5: 测试文件拆分 5→7
+
+**选择**: 按职责拆分
+
+| 新文件 | 来源 | 职责 |
+|--------|------|------|
+| `providers.spec.ts` | 重写 `providers.spec.ts` + `crud.spec.ts` 供应商部分 | 供应商完整 CRUD 验证 |
+| `models.spec.ts` | 新增，来自 `crud.spec.ts` 模型部分 | 模型管理完整验证 |
+| `stats.spec.ts` | 重写 `stats.spec.ts` + 合并 `stats-cards.spec.ts` | 统计页面完整验证 |
+| `navigation.spec.ts` | 新增，来自 `sidebar.spec.ts` + 导航测试 | 导航和侧边栏 |
+| `validation.spec.ts` | 新增，来自 `crud.spec.ts` 表单验证部分 | 表单校验测试 |
+| `fixtures.ts` | 新增 | 共享常量和 seed 工具函数 |
+| `global-setup.ts` / `global-teardown.ts` | 新增 | 临时目录生命周期 |
+
+### Decision 6: 进程启动顺序
+
+**选择**: Playwright `webServer` 数组，后端在前、前端在后
+
+**理由**: Playwright 按数组顺序依次等待每个 webServer 的 `url` 就绪。后端先启动（`/health` 返回 200），再启动前端（Vite 默认端口 5173）。`timeout: 60000` 覆盖 Go 首次编译耗时。两个 webServer 均设 `reuseExistingServer: false`，确保每次运行都是全新进程。
+
+## Risks / Trade-offs
+
+- **[Go 编译缓存]** → 首次 `go run` 需要 5-10s 编译，后续利用 Go 构建缓存加速。`timeout: 60000` 提供充足缓冲。如仍嫌慢，可手动 `cd backend && go build ./cmd/server/` 预编译。
+- **[端口 19026 冲突]** → 概率极低。Playwright 报明确错误，用户手动释放即可。不考虑自动重试。
+- **[Ctrl+C 强退临时文件残留]** → `globalTeardown` 不执行，但下次运行创建新目录，旧目录不占端口。可接受。
+- **[SQLite WAL 文件]** → 后端进程被 Playwright 强杀时可能留下 `.db-wal`/`.db-shm` 文件，但随临时目录一起删除，无影响。
+- **[sql.js 串行化约束]** → seed 数据时需确保 API 操作完成后再操作 SQLite。在 `beforeAll` 中串行执行，不存在并发问题。
--- a/openspec/changes/e2e-real-backend/proposal.md
+++ b/openspec/changes/e2e-real-backend/proposal.md
@@ -0,0 +1,29 @@
+## Why
+
+前端 E2E 测试当前只启动 Vite dev server，不启动后端。所有涉及写操作（创建/编辑/删除供应商、模型）的测试无法验证数据是否真正持久化，大量测试在缺少数据时直接 skip。测试实质上只是 UI 组件存在性检查，不是真正的端到端验证。后端已有完善的 CLI 参数机制（`--server-port`、`--database-path` 等）和 SQLite 文件数据库，具备每次测试使用干净隔离环境的天然条件。
+
+## What Changes
+
+- Playwright 配置改为双 `webServer` 模式，自动启动 Go 后端（隔离临时数据库）+ Vite 前端
+- `vite.config.ts` 的 proxy target 改为通过环境变量动态配置，E2E 时指向测试后端（19026），日常开发回退默认值（9826）
+- 新增 `e2e/fixtures.ts` 共享工具模块，提供 API seed 和 SQLite seed（通过 sql.js 直接操作临时数据库插入统计数据）
+- 新增 `e2e/global-setup.ts` 和 `e2e/global-teardown.ts` 管理临时目录生命周期
+- 重写全部 E2E 测试文件（5→7 个），覆盖完整 CRUD 验证、统计数据验证、导航、表单校验
+- 新增 `sql.js` + `@types/sql.js` 依赖（纯 WASM，零原生编译，Windows 兼容）
+
+## Capabilities
+
+### New Capabilities
+
+- `e2e-testing`: 前端 E2E 测试基础设施，定义 Playwright 双 webServer 启动模式、临时文件隔离、端口策略、环境变量传递、统计数据 seed 方式、测试文件组织结构
+
+### Modified Capabilities
+
+（无 — 现有 `test-coverage` spec 中的 E2E 要求不变，本 change 提供实现手段使其得到真正满足）
+
+## Impact
+
+- **代码变更**: `frontend/vite.config.ts`（1 行）、`frontend/playwright.config.ts`（重写）、`frontend/e2e/` 目录（新增 5 文件 + 重写 3 文件 + 删除 2 文件）
+- **新增依赖**: `sql.js`、`@types/sql.js`（devDependencies）
+- **后端无变更**: 仅通过 CLI 参数以隔离模式启动现有后端，不修改后端代码
+- **开发体验零侵入**: 日常 `bun run dev` 行为不变，仅 `bun run test:e2e` 启动真实后端
--- a/openspec/changes/e2e-real-backend/specs/e2e-testing/spec.md
+++ b/openspec/changes/e2e-real-backend/specs/e2e-testing/spec.md
@@ -0,0 +1,216 @@
+## ADDED Requirements
+
+### Requirement: E2E 测试基础设施
+
+前端 E2E 测试 SHALL 自动启动隔离的 Go 后端实例，提供真实 API 交互能力。
+
+#### Scenario: 双 webServer 自动启动
+
+- **WHEN** 执行 `bun run test:e2e`
+- **THEN** Playwright SHALL 按 webServer 数组顺序先启动 Go 后端（端口 19026），再启动 Vite 前端（端口 5173）
+- **THEN** Go 后端 SHALL 使用临时目录中的独立数据库文件和日志目录
+- **THEN** Go 后端启动命令 SHALL 包含 `--server-port 19026`、`--database-path`、`--log-path`、`--log-level warn` 参数
+- **THEN** Go 后端 cwd SHALL 指向 `backend/` 目录
+- **THEN** webServer 等待超时 SHALL 为 60000ms
+- **THEN** 两个 webServer SHALL 设置 `reuseExistingServer: false`
+
+#### Scenario: 环境变量传递
+
+- **WHEN** Playwright 配置加载
+- **THEN** `playwright.config.ts` SHALL 设置 `process.env.NEX_BACKEND_PORT` 为 `'19026'`
+- **THEN** `process.env.NEX_E2E_TEMP_DIR` SHALL 设置为临时目录路径
+- **THEN** Vite dev server 子进程 SHALL 自动继承上述环境变量
+- **THEN** E2E 测试文件 SHALL 通过 `process.env` 读取后端端口和临时目录信息
+
+#### Scenario: Vite proxy 动态化
+
+- **WHEN** `vite.config.ts` 配置 proxy target
+- **THEN** proxy target SHALL 读取 `process.env.NEX_BACKEND_PORT`，回退到 `'9826'`
+- **THEN** 日常 `bun run dev` 时（无环境变量）proxy target SHALL 为 `http://localhost:9826`
+- **THEN** E2E 测试时 proxy target SHALL 为 `http://localhost:19026`
+
+### Requirement: 临时文件隔离
+
+E2E 测试 SHALL 使用临时目录隔离所有文件，测试结束后自动清理。
+
+#### Scenario: 临时目录创建
+
+- **WHEN** Playwright 配置加载
+- **THEN** SHALL 使用 `fs.mkdtempSync(path.join(os.tmpdir(), 'nex-e2e-'))` 创建临时目录
+- **THEN** 临时目录 SHALL 包含 `test.db`（数据库）和 `log/`（日志）子路径
+
+#### Scenario: 临时目录清理
+
+- **WHEN** Playwright 所有测试完成
+- **THEN** `globalTeardown` SHALL 使用 `fs.rm(dir, { recursive: true, force: true })` 删除临时目录
+- **THEN** 清理 SHALL 在 webServer 进程关闭之后执行
+
+### Requirement: 统计数据 seed
+
+E2E 测试 SHALL 能通过 sql.js 直接操作 SQLite 文件 seed 历史统计数据。
+
+#### Scenario: SQLite 统计数据插入
+
+- **WHEN** 统计页面测试需要历史数据
+- **THEN** SHALL 使用 sql.js 打开临时数据库文件
+- **THEN** SHALL 通过 `INSERT INTO usage_stats` 插入指定日期和请求量的统计数据
+- **THEN** SHALL 将修改后的数据库写回文件（`db.export()` → `fs.writeFileSync`）
+- **THEN** seed 操作 SHALL 在 API 创建供应商和模型之后串行执行
+- **THEN** seed 完成后 SHALL 关闭 sql.js 数据库连接
+
+### Requirement: E2E 共享工具模块
+
+E2E 测试 SHALL 提供共享工具模块（`e2e/fixtures.ts`）封装常用操作。
+
+#### Scenario: 共享常量
+
+- **WHEN** 测试文件需要后端 API 地址
+- **THEN** fixtures SHALL export `API_BASE` 常量，值为 `http://localhost:${process.env.NEX_BACKEND_PORT}`
+
+#### Scenario: API seed 工具
+
+- **WHEN** 测试需要通过 API 准备数据
+- **THEN** fixtures SHALL export `seedProvider(request, data)` 函数，通过 `request.post` 创建供应商
+- **THEN** fixtures SHALL export `seedModel(request, data)` 函数，通过 `request.post` 创建模型
+
+#### Scenario: SQLite seed 工具
+
+- **WHEN** 测试需要 seed 统计数据
+- **THEN** fixtures SHALL export `seedUsageStats(statsData)` 函数，通过 sql.js 插入 `usage_stats` 记录
+
+### Requirement: 供应商管理 E2E 测试
+
+E2E 测试 SHALL 验证供应商的完整 CRUD 用户流程。
+
+#### Scenario: 创建供应商并验证
+
+- **WHEN** 用户通过 UI 填写供应商表单并提交
+- **THEN** 对话框 SHALL 关闭
+- **THEN** 新供应商 SHALL 出现在表格中
+- **THEN** 表格 SHALL 显示正确的 id、name、base_url、协议、enabled 状态
+
+#### Scenario: 编辑供应商并验证
+
+- **WHEN** 用户点击编辑按钮、修改名称并提交
+- **THEN** 对话框 SHALL 关闭
+- **THEN** 表格中该供应商的名称 SHALL 更新为新值
+
+#### Scenario: 删除供应商并验证
+
+- **WHEN** 用户点击删除按钮并确认
+- **THEN** 确认框 SHALL 消失
+- **THEN** 该供应商 SHALL 从表格中消失
+
+### Requirement: 模型管理 E2E 测试
+
+E2E 测试 SHALL 验证模型的完整 CRUD 用户流程。
+
+#### Scenario: 前置数据准备
+
+- **WHEN** 模型测试开始前
+- **THEN** SHALL 通过 API seed 一个供应商（不通过 UI）
+
+#### Scenario: 创建模型并验证
+
+- **WHEN** 用户展开供应商行、填写模型表单并提交
+- **THEN** 对话框 SHALL 关闭
+- **THEN** 新模型 SHALL 出现在展开行的模型表格中
+- **THEN** 模型表格 SHALL 显示统一模型 ID（`provider_id/model_name` 格式）
+
+#### Scenario: 编辑模型并验证
+
+- **WHEN** 用户点击模型编辑按钮、修改并提交
+- **THEN** 对话框 SHALL 关闭
+- **THEN** 模型表格 SHALL 显示更新后的数据
+
+#### Scenario: 删除模型并验证
+
+- **WHEN** 用户点击模型删除按钮并确认
+- **THEN** 该模型 SHALL 从模型表格中消失
+
+### Requirement: 统计页面 E2E 测试
+
+E2E 测试 SHALL 验证统计页面的数据展示和筛选功能。
+
+#### Scenario: 统计数据准备
+
+- **WHEN** 统计测试开始前
+- **THEN** SHALL 通过 API seed 供应商和模型
+- **THEN** SHALL 通过 sql.js seed 多日历史统计数据（覆盖不同供应商、不同模型、不同日期）
+
+#### Scenario: 统计概览验证
+
+- **WHEN** 加载统计页面
+- **THEN** 统计摘要卡片 SHALL 显示正确的总请求量
+- **THEN** 统计摘要卡片 SHALL 显示正确的活跃模型数和活跃供应商数
+- **THEN** 统计表格 SHALL 显示 seed 的数据行
+
+#### Scenario: 统计筛选验证
+
+- **WHEN** 用户选择供应商筛选条件
+- **THEN** 统计表格 SHALL 只显示该供应商的数据
+- **WHEN** 用户输入模型名称筛选条件
+- **THEN** 统计表格 SHALL 只显示匹配模型的数据
+
+### Requirement: 导航 E2E 测试
+
+E2E 测试 SHALL 验证页面导航和侧边栏功能。
+
+#### Scenario: 侧边栏渲染
+
+- **WHEN** 加载任意页面
+- **THEN** 侧边栏 SHALL 显示应用名称和导航菜单项
+
+#### Scenario: 页面切换
+
+- **WHEN** 用户点击侧边栏导航菜单项
+- **THEN** 页面 SHALL 切换到对应路由并显示正确内容
+- **THEN** 当前菜单项 SHALL 高亮
+
+#### Scenario: URL 持久化
+
+- **WHEN** 用户在统计页面刷新浏览器
+- **THEN** 页面 SHALL 保持在统计页面
+
+### Requirement: 表单验证 E2E 测试
+
+E2E 测试 SHALL 验证表单的校验行为。
+
+#### Scenario: 供应商表单必填校验
+
+- **WHEN** 用户打开添加供应商对话框并直接点击保存
+- **THEN** SHALL 显示所有必填字段的验证错误提示
+
+#### Scenario: URL 格式校验
+
+- **WHEN** 用户在 base_url 字段输入无效 URL 并提交
+- **THEN** SHALL 显示 URL 格式错误提示
+
+#### Scenario: 对话框行为
+
+- **WHEN** 用户打开对话框后点击取消
+- **THEN** 对话框 SHALL 关闭且表单重置
+- **WHEN** 用户再次打开对话框
+- **THEN** 表单字段 SHALL 为空
+
+### Requirement: E2E 测试文件组织
+
+E2E 测试 SHALL 按 7 个 spec 文件组织。
+
+#### Scenario: 文件结构
+
+- **WHEN** 查看 `e2e/` 目录
+- **THEN** SHALL 包含以下测试文件：`providers.spec.ts`、`models.spec.ts`、`stats.spec.ts`、`navigation.spec.ts`、`validation.spec.ts`
+- **THEN** SHALL 包含以下辅助文件：`fixtures.ts`、`global-setup.ts`、`global-teardown.ts`
+- **THEN** SHALL NOT 包含已删除的文件：`stats-cards.spec.ts`、`sidebar.spec.ts`、`crud.spec.ts`
+
+### Requirement: 新增依赖
+
+E2E 测试 SHALL 引入 sql.js 作为 devDependency。
+
+#### Scenario: sql.js 依赖
+
+- **WHEN** 安装前端依赖
+- **THEN** `package.json` 的 devDependencies SHALL 包含 `sql.js`
+- **THEN** `package.json` 的 devDependencies SHALL 包含 `@types/sql.js`
+- **THEN** sql.js SHALL 仅在 E2E 测试的 seed 逻辑中使用，不影响生产代码
--- a/openspec/changes/e2e-real-backend/tasks.md
+++ b/openspec/changes/e2e-real-backend/tasks.md
@@ -0,0 +1,29 @@
+## 1. 基础设施
+
+- [x] 1.1 安装 sql.js 和 @types/sql.js 到 devDependencies（`bun add -d sql.js @types/sql.js`）
+- [x] 1.2 修改 `vite.config.ts` proxy target 为动态读取 `process.env.NEX_BACKEND_PORT || '9826'`
+- [x] 1.3 创建 `e2e/global-setup.ts`（空实现或验证临时目录存在）
+- [x] 1.4 创建 `e2e/global-teardown.ts`，读取 `process.env.NEX_E2E_TEMP_DIR`，用 `fs.rm` 递归删除
+- [x] 1.5 创建 `e2e/fixtures.ts`，导出 `API_BASE` 常量、`seedProvider`、`seedModel`、`seedUsageStats` 函数
+- [x] 1.6 重写 `playwright.config.ts`，创建临时目录、设置环境变量、配置双 webServer 数组（Go 后端 + Vite 前端）
+
+## 2. E2E 测试重写
+
+- [x] 2.1 重写 `e2e/providers.spec.ts`：空数据库开始，完整供应商 CRUD 验证（创建→验证→编辑→验证→删除→验证）
+- [x] 2.2 创建 `e2e/models.spec.ts`：beforeEach API seed 供应商，完整模型 CRUD 验证（展开行→创建模型→验证→编辑→验证→删除→验证）
+- [x] 2.3 重写 `e2e/stats.spec.ts`：beforeAll API seed 供应商+模型，sql.js seed 多日统计数据，验证概览卡片、表格数据、筛选功能
+- [x] 2.4 创建 `e2e/navigation.spec.ts`：侧边栏渲染、页面切换、URL 持久化验证（合并 sidebar.spec.ts）
+- [x] 2.5 创建 `e2e/validation.spec.ts`：供应商表单必填校验、URL 格式校验、对话框行为（取消重置、连续点击）
+
+## 3. 清理旧文件
+
+- [x] 3.1 删除 `e2e/crud.spec.ts`（内容已拆分到 providers/models/validation）
+- [x] 3.2 删除 `e2e/sidebar.spec.ts`（内容已合并到 navigation）
+- [x] 3.3 删除 `e2e/stats-cards.spec.ts`（内容已合并到 stats）
+
+## 4. 验证
+
+- [ ] 4.1 运行 `bun run test:e2e` 确认所有 E2E 测试通过
+- [ ] 4.2 确认临时目录在测试结束后被清理
+- [ ] 4.3 运行 `bun run dev` 确认日常开发行为不受影响（proxy 仍指向 9826）
+- [ ] 4.4 运行 `bun run test` 确认单元测试不受影响