tennis-training-hub/docs/testing.md

Testing Guide

Test layers

项目当前采用四层测试结构：

1. 静态检查

• pnpm check
• pnpm build
• go build ./...

用于保证类型、打包和 Go 媒体服务编译可通过。

2. 单元测试

• pnpm test

当前覆盖：

• Node/tRPC 路由输入校验与权限检查
• LLM 模块请求配置与环境变量回退逻辑
• 媒体工具函数，例如录制时长格式化与码率选择

3. Go 媒体服务测试

• pnpm test:go

当前覆盖：

• media/health
• 会话创建与状态聚合
• 归档流程的基础回放产物生成

4. 浏览器 E2E

• pnpm test:e2e

使用 Playwright。为保证稳定性：

• 启动本地测试服务器 pnpm dev:test
• 通过路由拦截模拟 tRPC 和 /media 接口
• 注入假媒体设备、假 MediaRecorder 和假 RTCPeerConnection

这样可以自动验证前端主流程，而不依赖数据库、真实摄像头权限和真实 WebRTC 网络环境。

Unified verification

一次性执行全部自动验证：

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 中的配置：

pnpm test:llm
pnpm test:llm -- "你好，做个自我介绍"

说明：

• 该命令会直接请求 LLM_API_URL
• 适合验证 LLM_API_KEY、LLM_MODEL 和网关连通性
• 不建议纳入 pnpm verify，因为它依赖外部网络和真实密钥

Production smoke checks

部署到宿主机后，建议至少补以下联测：

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/recorder
• 确认没有 pageerror 或首屏 console.error

Local browser prerequisites

首次运行 Playwright 前执行：

pnpm exec playwright install chromium

Notes

• E2E 目前验证的是“模块主流程是否正常”，不是媒体编码质量本身
• 若需要真实录制验证，可额外用本地 Chrome 和真实摄像头做手工联调
• 若 pnpm test:e2e 失败，优先检查：
  • PORT=3100 是否被占用
  • 浏览器依赖是否安装
  • 前端路由或测试标识是否被改动