183 行
6.0 KiB
Markdown
183 行
6.0 KiB
Markdown
# Testing Guide
|
||
|
||
## Test layers
|
||
|
||
项目当前采用四层测试结构：
|
||
|
||
### 1. 静态检查
|
||
|
||
- `pnpm check`
|
||
- `pnpm build`
|
||
- `go build ./...`
|
||
|
||
用于保证类型、打包和 Go 媒体服务编译可通过。
|
||
|
||
### 2. 单元测试
|
||
|
||
- `pnpm test`
|
||
|
||
当前覆盖：
|
||
|
||
- Node/tRPC 路由输入校验与权限检查
|
||
- 实时分析会话保存、管理员权限与异步 NTRP 刷新入队
|
||
- LLM 模块请求配置与环境变量回退逻辑
|
||
- 视觉模型 per-request model override 能力
|
||
- 视觉标准图库路由与 admin/H1 全量可见性逻辑
|
||
- 媒体工具函数，例如录制时长格式化与码率选择
|
||
- 实时分析动作片段保存、成就回写和 NTRP 刷新入队逻辑
|
||
|
||
### 3. Go 媒体服务测试
|
||
|
||
- `pnpm test:go`
|
||
|
||
当前覆盖：
|
||
|
||
- `media/health`
|
||
- 会话创建与状态聚合
|
||
- 归档流程的基础回放产物生成
|
||
|
||
### 4. 浏览器 E2E
|
||
|
||
- `pnpm test:e2e`
|
||
|
||
使用 Playwright。为保证稳定性：
|
||
|
||
- 启动本地测试服务器 `pnpm dev:test`
|
||
- 测试服务器启动前要求数据库已完成 Drizzle 迁移
|
||
- 通过路由拦截模拟 tRPC 和 `/media` 接口
|
||
- 注入假媒体设备、假 `MediaRecorder` 和假 `RTCPeerConnection`
|
||
|
||
这样可以自动验证前端主流程，而不依赖真实摄像头权限和真实 WebRTC 网络环境。
|
||
当前 E2E 已覆盖新的后台任务流、实时分析入口、录制焦点视图和任务中心依赖的接口 mock。
|
||
当前 E2E 还覆盖视频库轻剪辑工作台，包括建议片段渲染、轻剪辑入口和草稿导出入口。
|
||
|
||
2026-03-15 新增的回归重点：
|
||
|
||
- 后台任务查询失败时保留最近一次成功结果
|
||
- LLM 与 media service 外部请求超时/重试
|
||
- worker 心跳与超限任务失败收敛
|
||
- 实时分析动作分布、区间筛选和会话质量带
|
||
- PC 轻剪辑循环预览、清单导出和草稿增强
|
||
- 教程库非网球数据清洗与 `topicArea=tennis_skill` 线上返回校验
|
||
|
||
首次在新库或新 schema 上执行前，先跑：
|
||
|
||
```bash
|
||
set -a && source .env && set +a && pnpm exec drizzle-kit migrate
|
||
```
|
||
|
||
## Unified verification
|
||
|
||
一次性执行全部自动验证：
|
||
|
||
```bash
|
||
pnpm verify
|
||
```
|
||
|
||
执行顺序：
|
||
|
||
1. `pnpm check`
|
||
2. `pnpm test`
|
||
3. `pnpm test:go`
|
||
4. `pnpm build`
|
||
5. `pnpm test:e2e`
|
||
|
||
## Live LLM smoke test
|
||
|
||
使用真实 LLM 网关验证当前 `.env` 中的配置：
|
||
|
||
```bash
|
||
pnpm test:llm
|
||
pnpm test:llm -- "你好，做个自我介绍"
|
||
```
|
||
|
||
说明：
|
||
|
||
- 该命令会直接请求 `LLM_API_URL`
|
||
- 适合验证 `LLM_API_KEY`、`LLM_MODEL` 和网关连通性
|
||
- 不建议纳入 `pnpm verify`，因为它依赖外部网络和真实密钥
|
||
|
||
多模态链路建议额外执行一次手工 smoke test：
|
||
|
||
```bash
|
||
pnpm exec tsx -e 'import "dotenv/config"; import { invokeLLM } from "./server/_core/llm"; const result = await invokeLLM({ model: process.env.LLM_VISION_MODEL, apiUrl: process.env.LLM_VISION_API_URL, apiKey: process.env.LLM_VISION_API_KEY, messages: [{ role: "user", content: [{ type: "text", text: "请用中文一句话描述图片" }, { type: "image_url", image_url: { url: "https://..." } }] }] }); console.log(result.model, result.choices[0]?.message?.content);'
|
||
```
|
||
|
||
如果返回模型与 `LLM_VISION_MODEL` 不一致，说明上游网关忽略了视觉模型选择，业务任务会自动回退到文本纠正结果。
|
||
|
||
视觉标准图库的真实 smoke test 可直接复用内置数据：
|
||
|
||
- 初始化 `ADMIN_USERNAMES=H1`
|
||
- 登录 `H1` 后访问 `/vision-lab`
|
||
- 检查标准图是否已经入库
|
||
- 运行单张或批量测试，确认结果会写入 `vision_test_runs`
|
||
- 若上游视觉网关不可用，记录应显示 `fallback`
|
||
|
||
2026-03-15 额外完成了多模态兼容与历史修复验证：
|
||
|
||
- 使用真实公网网球图片调用视觉链路，确认服务端能兼容上游返回的非标准 JSON 字段
|
||
- 重跑历史 3 条 `fallback` 标准图记录，确认已全部转为 `visionStatus=ok`
|
||
- Playwright 真实站点检查 `https://te.hao.work/vision-lab`，确认页面不再出现 `Cannot read properties of undefined (reading 'join')`
|
||
|
||
## Production smoke checks
|
||
|
||
部署到宿主机后，建议至少补以下联测：
|
||
|
||
```bash
|
||
docker compose ps
|
||
curl -I https://te.hao.work/
|
||
curl http://127.0.0.1:8081/media/health
|
||
pnpm test:llm
|
||
```
|
||
|
||
推荐再增加一轮浏览器级检查：
|
||
|
||
- 打开 `https://te.hao.work/`
|
||
- 打开 `https://te.hao.work/login`
|
||
- 打开 `https://te.hao.work/checkin`
|
||
- 打开 `https://te.hao.work/admin`（管理员）
|
||
- 打开 `https://te.hao.work/recorder`
|
||
- 打开 `https://te.hao.work/live-camera`
|
||
- 确认没有 `pageerror` 或首屏 `console.error`
|
||
|
||
真实站点 Playwright smoke script 可直接复用：
|
||
|
||
```bash
|
||
xvfb-run -a bash -lc 'cd /root/.codex/skills/playwright-skill && node run.js /tmp/playwright-te-smoke.js'
|
||
```
|
||
|
||
2026-03-15 已实际完成一次真实环境联调：
|
||
|
||
- 初次 smoke 发现 `https://te.hao.work/checkin` 仍显示旧版“每日打卡 / 训练打卡”，确认现网落后于仓库代码
|
||
- 执行 `docker compose up -d --build migrate app app-worker` 后再次 smoke
|
||
- 复测 `login / checkin / videos / recorder / live-camera / admin` 全部通过，且未捕获 `pageerror` / `console.error`
|
||
|
||
2026-03-15 08:00 CST 又完成一轮完整验证：
|
||
|
||
- `pnpm check` 通过
|
||
- `pnpm test` 通过（104/104）
|
||
- `pnpm test:go` 通过
|
||
- `pnpm build` 通过
|
||
- `pnpm test:e2e` 通过（7/7）
|
||
- `pnpm test:llm` 通过
|
||
- 本地测试库补齐并应用 `0008_tutorial_academy_refresh` migration 后，`pnpm dev:test` 与 E2E 链路恢复正常
|
||
- 线上 smoke 复测 `dashboard / training / videos / vision-lab / live-camera / recorder / admin` 全部通过，`issueCount: 0`
|
||
|
||
## Local browser prerequisites
|
||
|
||
首次运行 Playwright 前执行：
|
||
|
||
```bash
|
||
pnpm exec playwright install chromium
|
||
```
|
||
|
||
## Notes
|
||
|
||
- E2E 目前验证的是“模块主流程是否正常”，不是媒体编码质量本身
|
||
- 若需要真实录制验证，可额外用本地 Chrome 和真实摄像头做手工联调
|
||
- 若 `pnpm test:e2e` 失败，优先检查：
|
||
- 本地数据库是否已执行最新 Drizzle 迁移
|
||
- `PORT=3100` 是否被占用
|
||
- 浏览器依赖是否安装
|
||
- 前端路由或测试标识是否被改动
|