VCR 使用指南

VCR（Video Cassette Recorder）用于在自动化测试中对 LLM API 调用进行录制与回放，让测试在离线/CI 环境中也能稳定运行。

目录

• 快速开始
• 模式与环境变量
• Fixtures 目录结构
• 编写测试
• 故障排查

快速开始

# 默认：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 决定）：

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；避免测试静默访问网络。