[RFC] 084 - 为 LLM Providers 添加集成测试

[BrandonStudio]

目前，所有的 LLM Provider 都是单元测试，一个函数一个函数地测，测这个函数的时候就会把其它的函数都mock掉，这样对集成之后的逻辑没有验证。

提议增加集成测试，对每一个 Provider，只将 globalThis.fetch mock掉，使用真实环境下的响应进行测试。

[arvinxx]

感觉合理的，回头看下怎么加

[BrandonStudio]

可能对 Cloudflare 那部分我回头就会加一下，就是把响应的真实流式输出放过去

[BrandonStudio]

有关集成测试的问题汇总

目前 #7326 尝试对 Azure AI Foundry 添加了集成测试，但是尚未成功。
将目前的问题进行汇总，并在此讨论解决方案。

1. Edge Runtime 包解析问题

如前所述，模型提供商的集成测试离不开对请求的完整打桩，由于模型提供商部分的代码全部使用了 Edge Runtime，而 Edge Runtime 使用 fetch 进行请求，因此集成测试的重要任务是对 fetch 进行打桩。

在对 Azure AI Foundry 设计的集成测试中发现，打了桩的 fetch 函数没有被调用。

断言代码

（以下代码归属于 #7326 ）

lobe-chat/src/libs/agent-runtime/azureai/integration.test.ts

Lines 339 to 346 in 7e4ec8e

	expect(mockFetch).toHaveBeenCalledWith(
	`${endpoint}${chatCompletionPath}?api-version=${apiVersion}`,
	expect.objectContaining({
	method: 'POST',
	headers: expect.anything(),
	body: expect.any(String),
	}),
	);

lobe-chat/src/libs/agent-runtime/azureai/integration.test.ts

Lines 438 to 445 in 7e4ec8e

	expect(mockFetch).toHaveBeenCalledWith(
	`${endpoint}${chatCompletionPath}?api-version=${apiVersion}`,
	expect.objectContaining({
	method: 'POST',
	headers: expect.anything(),
	body: expect.any(String),
	}),
	);

经过反复调试定位，发现异常现象来自于包的解析策略。
在 Next.js Edge Runtime 中，模块包应解析为 browser 版本，但是 vitest 的测试环境中，edge runtime 测试环境并不会更改包的解析策略，模块包实际上解析为 esm 版本。该版本的 @azure/core-rest-pipeline 使用 node:https 作为请求发送终端，因此没有经过 fetch。
关联的 Issue：vitest-dev/vitest#7699

Vitest 成员说明应修改 vitest.config.ts 中的解析策略：vitest-dev/vitest#7699 (comment)
不过，该修改会影响全部 vitest.config.ts 中定义的测试，可能对其它测试造成影响。

为此，Vitest 成员建议，使用多个 vitest.config.ts，可以将走 Edge Runtime 的测试全部移动到另一个配置文件中，例如 vitest.edge.config.ts。

2. JetBrains WebStorm 不支持对多个 vitest 配置文件的发现

@arvinxx 反对使用多个 vitest 配置文件，理由是 WebStorm 不支持 vitest.config.ts 以外的其它测试配置文件的自动测试发现，无法在 IDE 中便捷地对单个测试用例或单组测试用例进行快速测试。

Visual Studio Code 的 Vitest 扩展默认支持3个测试配置文件的发现，不过，@arvinxx 习惯于 WebStorm，不希望切换到 VS Code。
我没有使用过 WebStorm，没有研究过它的测试发现，也没有研究过是否可以通过某些配置支持多个文件。不排除有某种支持这一需求的高级方法，有待研究。
除此之外，Wallaby.js 插件似乎也支持在 WebStorm 中自动测试发现，该插件对开源软件免费。但是，如前所述，我没有用过 WebStorm，没有进行过尝试。阅读文档感觉可能需要某些额外的代码，但是该部分可能与测试功能无关。有待研究。 Wallaby.js 的开源许可不适用于本项目。

针对这一问题，提出2种解决思路：

1. 开发一 npm 包，支持将不同测试配置文件链接到 vitest.config.ts。例如，使用单独的文件夹 vitest-configs 存储全部测试配置文件 vitest.happy-dom.ts, vitest.edge.ts, vitest.node.ts，通过该 CLI 工具自动创建 vitest.config.ts 到 vitest.edge.ts 的链接，并且可以快速切换。
2. 使用 Vitest Workspace 功能，将不同种类的配置设置为不同的工作区（现在称为项目），合并到唯一的 vitest.config.ts。

方案2看上去更加优雅。

3. Vitest / Vite Workspace 嵌套包解析问题

在刚才的 Issue 中询问 Vitest 成员是否可以使用 Workspace，该成员回复：vitest-dev/vitest#7699 (comment)
Vitest 有一已知的嵌套包解析问题：vitest-dev/vitest#5301
简而言之，在 Workspace 中定义的测试文件中导入的包 A 中引用的包 B, C, D, ... 不受 Vitest 控制。

举例来说，test1.test.ts 包含于某一个 Workspace 配置中，其包含对包 A 的导入：

import { Config } from 'A';

而包 A 中又有对 B 的导入

export { Config } from 'B';

此时，在 test1.test.ts 中，对 B 的打桩 vi.mock('B', ...) 无效，在 workspace.config.ts 中配置的包解析策略无效。

经多次调试跟踪，这一问题似乎可以追溯到 Vite，而不是单单 Vitest 的问题。该问题尚未解决。

问题似乎又回到了原点。

解决方案讨论

此处汇总可能的解决方案及当前面临的问题。

1. 使用 Workspace 配置
   • 当前问题：嵌套导入问题 Vitest doesn't honor resolve conditions for nested modules in workspace. vitest-dev/vitest#5301
   • 解决方案：暂无，棘手
2. 使用多个 vitest 配置文件
   • 当前问题：WebStorm 无法对多个配置文件自动发现
   • 解决方案：容易
     • 换用 Visual Studio Code
     • 调研 WebStorm 和 Wallaby.js，寻求可能的方法
     • 编写 npm 包，自动切换链接到不同的测试配置
     • 放弃自动测试发现，仅保证 CLI 脚本可用，CI 测试正常
3. 使用现有 vitest 配置文件框架
   • 当前问题：修改解析策略会影响其它测试
   • 解决方案：待讨论，见下

对现有配置文件方法的附加讨论

要点1：现有2个 Vitest 配置文件，分别是 vitest.config.ts 和 vitest.server.config.ts

vitest.config.ts 是主测试配置，包含全部非服务器测试。vitest.server.config.ts 包含服务器测试，在 CI 中会启动一个临时的假数据库进行测试。

要点2：更改的模块解析配置处于 ssr 中，只影响 edge-runtime 和 node，不影响 happy-dom

添加 ssr.resolve 配置之后的失败测试见此处。
这其中似乎有部分服务端测试（配置为 node）在 vitest.config.ts。不清楚这些文件测试两遍的目的是什么 @arvinxx 。内部引用（Discord@20250409-13:04）

如果可以确认所有 vitest.config.ts 中包含的测试都是 edge-runtime 和 happy-dom 的，没有 node 的，那么就可以放心地直接修改 vitest.config.ts 中的 ssr.resolve。

对专用 npm 链接工具设计的补充说明

可以考虑 git 仓库中本身不包含 vitest.config.ts，在根目录下有 vitest.happy-dom.config.ts, vitest.edge.config.ts, vitest.server.config.ts。

• 本地检测到正在使用 WebStorm 时，或者通过手动触发，创建一个名为 vitest.config.ts 的链接，目标是以上三个文件之一
• 本地使用 Visual Studio Code 时，不进行任何操作。此时 Vitest 扩展会自动发现三个配置文件中的测试
• CI 中不需要测试发现，分别对三个测试文件执行测试即可

[arvinxx]

个人更加偏向 vitetest Workspace 的方案，是看起来最 promising 的解法，看看有没有可能推动下 vitest 团队解决？

如果可以确认所有 vitest.config.ts 中包含的测试都是 edge-runtime 和 happy-dom 的，没有 node 的，那么就可以放心地直接修改 vitest.config.ts 中的 ssr.resolve。

vitest.config.ts 是会包含 node 的相关的执行的。比如 src/server/services/nextAuthUser 等都是会用 vitest.config.ts 来跑（只是这个文件的顶部会加上 nodejs 的runtime 配置

[BrandonStudio]

这个问题已经持续一年半了，是非常底层的包解析问题，底层到 Vite 的基础设施，我感觉很难调试。目前看来不太可能短时间内修复。

我要确认的问题是，这些 node 环境的测试是否必须要在客户端执行一次？有没有可能直接放到 server.config.ts 里面跑？