三环境测试全覆盖：OpenRouter ai-sdk-provider Node、Edge与E2E测试体系解析

如果你正在使用 OpenRouter 的 ai-sdk-provider（Vercel AI SDK 的 OpenRouter Provider），一定关心它如何保证在 Node.js 与 Edge 运行环境、以及真实 API 下都稳定可用。这个项目用Node、Edge、E2E 三套测试环境加上一套 issue 回归测试，实现了从单元测试到真实模型调用的全覆盖。本文带你用 10 分钟看懂 ai-sdk-provider 的这套测试体系是怎么搭起来的。

为什么需要三环境测试？

一个 AI SDK Provider 会同时运行在两类完全不同的运行时里：

• Node.js 环境：传统服务端、CLI 工具，可以使用文件系统、Node 内置模块；
• Edge 环境：Vercel Edge Functions 等边缘计算场景，运行时能力受限（无完整 Node API、无文件系统）。

如果只在 Node 里测，代码里悄悄用了fs之类的 API，到 Edge 上线时就会踩坑；如果只测本地 mock，真实的模型响应格式（流式分片、工具调用、reasoning 元数据）变化又测不出来。因此项目选择：同一套单元测试在两个运行时各跑一遍，再用 E2E 打真实 API。

测试脚本定义在 package.json 中：

所有配置都基于 Vitest，并通过vite-tsconfig-paths插件支持@/src这样的路径别名，还统一注入了__PACKAGE_VERSION__常量（见 vitest.node.config.ts）。

Node 单元测试：零成本跑全量用例

单元测试全部位于src/下，与被测源码同目录，例如 src/chat/index.test.ts、src/tests/usage-accounting.test.ts、src/utils/resolve-reasoning.ts 等。

关键点在于它们不需要 API Key：请求由 AI SDK 官方的 mock 测试服务器createTestServer（来自@ai-sdk/test-server）拦截并返回预置的 OpenRouter 风格响应，覆盖聊天、补全、嵌入、重排、图像、视频等各模块（模块入口见 src/index.ts）。

好处非常直观：

• 🚀 跑得快：本地几秒到几十秒即可全量通过；
• 🔁 结果确定：mock 响应固定，断言可以精确到 token 用量、finish reason、流式分片；
• 🧪 免费：不消耗真实额度，可以放心放进 CI 每次都跑。

Edge 测试：同一套用例换个运行时再跑一遍

对比 vitest.node.config.ts 和 vitest.edge.config.ts，两者的唯一实质差异是environment字段：

• Node 配置：environment: 'node'
• Edge 配置：environment: 'edge-runtime'（由@edge-runtime/vm提供的 VM 模拟）

测试用例范围完全相同（都是src/**/*.test.ts）。也就是说，Edge 测试不是"另一批用例"，而是把 Node 通过的全量单测在 Edge 运行时里重放一遍。任何依赖 Node 专属 API 的写法都会在pnpm test:edge阶段现形。

对于需要在 Vercel 边缘函数里部署 AI 应用的开发者，这一步相当于免费的"上线前体检"。

E2E 测试：用真实 API 验证真模型

单元测试管"逻辑正确"，E2E 管"线上行为正确"。vitest.e2e.config.ts 的配置包含三个关键动作：

1. 通过dotenv加载.env.e2e中的环境变量（vitest.e2e.config.ts）；
2. include指向./e2e/**/*.test.ts；
3. exclude明确排除./e2e/issues/**/*.test.ts——回归测试单独管理，后文详述。

.env.e2e需要自己创建，仓库提供了模板 example.env.e2e，只需两个变量：

# Rename to .env.e2e OPENROUTER_API_BASE=https://openrouter.ai OPENROUTER_API_KEY=you-api-key-here

e2e/目录按能力划分场景，每个文件都调用真实模型：

以缓存测试为例（e2e/cache-control.test.ts）：第一次调用预热缓存，第二次调用断言cachedTokens > 0——这类"行为级"断言是 mock 测试很难覆盖的。真实请求耗时较长，所以用例会单独放宽超时，例如vi.setConfig({ testTimeout: 42_000 })。

e2e/issues：把每个 Bug 变成一条回归用例

这是整个体系里最有特色的一环：e2e/issues/ 目录下有45 个issue-*.test.ts文件，每一个都对应一个真实报障的 GitHub issue，例如 e2e/issues/issue-194-grok-invalid-json.test.ts。

文件头部的注释就是"问题档案"，例如（issue-194-grok-invalid-json.test.ts）：

Regression test for GitHub issue #194 Reported error: "AI_APICallError: Invalid JSON response" Model: x-ai/grok-4-fast (retired; the test now uses x-ai/grok-4.20)

命名规范为issue-{编号}-{简短描述}.test.ts，测试内容覆盖generateText、streamText、工具调用三条链路，确保该 bug 永不复发。

那为什么不用一个 e2e 命令全跑？vitest.issues.config.ts 的注释解释了原因：

• 回归测试可能命中不同模型/API，容易慢或被限流；
• 目的与功能测试不同——是"回归监控"而非"功能验证"；
• 适合按需运行或放入独立的 CI 任务。

所以主 e2e 套件用exclude把它们挡在外面（vitest.e2e.config.ts），需要时用pnpm test:issues单独执行。这套约定完整记录在 CONTRIBUTING.md 的 "Issue-Specific Regression Tests" 章节。

本地运行快速上手 🛠️

# 1. 安装依赖 pnpm install # 2. 跑 Node + Edge 全量单元测试（无需任何密钥） pnpm test # 3. （可选）准备 E2E 环境：复制 example.env.e2e 为 .env.e2e 并填入 API Key # 然后按需运行真实 API 测试 pnpm test:e2e # 功能级 E2E pnpm test:issues # issue 回归测试

CI 侧的门槛也写在 CONTRIBUTING.md：提交 PR 前需通过pnpm stylecheck、pnpm typecheck、pnpm build、pnpm test全套检查。

小结

ai-sdk-provider 的测试体系可以概括为一张"三环境 + 一档案"的地图：

• 🔹Node 单测：mock 服务器驱动，快速、免费、确定性强；
• 🔹Edge 单测：同一批用例在edge-runtime重放，提前暴露运行时兼容问题；
• 🔹E2E：真实 API 验证缓存、工具调用、PDF、视频等核心能力；
• 🔹issues 回归档案：每个历史 bug 对应一条命名规范的回归用例，按需运行、可长期监控。

对使用者而言，这意味着你可以放心地把它部署到 Node 或 Edge 环境；对贡献者而言，CONTRIBUTING.md 里的规范 + 现成的测试目录结构，让"修一个 bug 并防止它复发"变成了一套标准动作。