mirror of
https://github.com/linshenkx/prompt-optimizer.git
synced 2026-05-07 14:06:53 +08:00
97 lines
3.0 KiB
Markdown
97 lines
3.0 KiB
Markdown
# VCR 使用指南
|
||
|
||
VCR（Video Cassette Recorder）用于在自动化测试中对 LLM API 调用进行**录制**与**回放**，让测试在离线/CI 环境中也能稳定运行。
|
||
|
||
## 目录
|
||
|
||
- [快速开始](#快速开始)
|
||
- [模式与环境变量](#模式与环境变量)
|
||
- [Fixtures 目录结构](#fixtures-目录结构)
|
||
- [编写测试](#编写测试)
|
||
- [故障排查](#故障排查)
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 默认：auto 模式（有 fixture 就回放；缺 fixture 且未启用真实 API 时会失败或降级，取决于测试/拦截层）
|
||
pnpm test
|
||
|
||
# 强制回放（CI 推荐）：缺 fixture 或未拦截请求会直接失败
|
||
pnpm test:replay
|
||
|
||
# 重新录制（真实 API）：会产生费用，需配置 API Key
|
||
pnpm test:record
|
||
|
||
# 禁用 VCR（真实 API）：会产生费用，需配置 API Key
|
||
pnpm test:real
|
||
```
|
||
|
||
## 模式与环境变量
|
||
|
||
VCR 的行为由以下环境变量控制：
|
||
|
||
- `VCR_MODE`: `auto` | `record` | `replay` | `off`
|
||
- `ENABLE_REAL_LLM=true`: 允许真实 API（用于 `record`/`off`）
|
||
- `RUN_REAL_API=1`: 兼容 core 包已有开关（等价于 `ENABLE_REAL_LLM=true`）
|
||
|
||
项目已提供脚本（根目录 `package.json`）：
|
||
|
||
- `pnpm test:record` 等价于 `VCR_MODE=record ENABLE_REAL_LLM=true pnpm test`
|
||
- `pnpm test:replay` 等价于 `VCR_MODE=replay pnpm test`
|
||
- `pnpm test:real` 等价于 `VCR_MODE=off ENABLE_REAL_LLM=true pnpm test`
|
||
|
||
## Fixtures 目录结构
|
||
|
||
默认 fixtures 目录位于：
|
||
|
||
- `packages/core/tests/fixtures/`
|
||
|
||
按提供商/场景名组织：
|
||
|
||
- `packages/core/tests/fixtures/llm/<provider>/<scenario>.json`
|
||
|
||
示例：
|
||
|
||
- `packages/core/tests/fixtures/llm/deepseek/optimize-simple-prompt.json`
|
||
|
||
## 编写测试
|
||
|
||
在 core 包测试中，优先使用 `withVCR()` 包住真实调用（录制/回放由 VCR 决定）：
|
||
|
||
```ts
|
||
import { withVCR } from '../utils/vcr'
|
||
|
||
const response = await withVCR(
|
||
'optimize-simple-prompt',
|
||
{ provider: 'deepseek', model: 'deepseek-chat', messages: [{ role: 'user', content: 'hi' }], stream: true },
|
||
async () => {
|
||
// 这里放真实 API 调用（record/off 模式会实际发请求）
|
||
return await llmService.optimizePromptStream(...)
|
||
}
|
||
)
|
||
```
|
||
|
||
核心原则：
|
||
|
||
- 日常开发/CI：使用 `replay`，确保测试离线可重复
|
||
- 需要更新 fixtures：使用 `record` 并显式启用真实 API（`ENABLE_REAL_LLM=true`）
|
||
- fixtures 需要纳入版本控制（避免 CI 缺失导致不稳定）
|
||
|
||
## 故障排查
|
||
|
||
1) `Fixture not found`
|
||
|
||
- 说明当前处于回放路径但缺少 fixture。
|
||
- 解决：运行 `pnpm test:record` 生成 fixture，并将 `packages/core/tests/fixtures/` 纳入提交。
|
||
|
||
2) `Real LLM is disabled. Cannot record fixture.`
|
||
|
||
- 说明正在录制，但未启用真实 API。
|
||
- 解决：运行 `pnpm test:record`（已自动设置 `ENABLE_REAL_LLM=true`），并确保 `.env.local` 中配置了对应 API Key。
|
||
|
||
3) 回放时出现“未拦截请求”错误
|
||
|
||
- `pnpm test:replay` 会以更严格的方式运行，任何未被 fixtures/MSW 覆盖的请求都应视为失败。
|
||
- 解决：补齐对应 fixture 或补齐拦截/handlers；避免测试静默访问网络。
|
||
|