集成测试

集成测试用于验证 Agent 能否与模型 API 和外部服务正确协作。不同于使用伪实现和模拟对象的单元测试，集成测试会进行真实的网络调用，以确认组件能够协同工作、凭证有效，并且延迟表现可接受。由于 LLM 响应具有非确定性，集成测试需要采用不同于传统软件测试的策略。本指南介绍如何为 Agent 组织、编写和运行集成测试。有关为 LangChain 本身贡献代码时使用的通用测试基础设施，请参阅贡献代码。

分离单元测试和集成测试

集成测试速度较慢，并且需要 API 凭证，因此请将它们与单元测试分开。这样可以让你在每次变更时运行快速的单元测试，并将集成测试留给 CI 或部署前检查。使用文件命名约定分离集成测试。将集成测试文件命名为 *.int.test.ts，并配置 vitest，使其从默认运行中排除这些文件：

vitest.config.ts

import { configDefaults, defineConfig } from "vitest/config";

export default defineConfig((env) => {
  if (env.mode === "int") {
    return {
      test: {
        testTimeout: 100_000,
        include: ["**/*.int.test.ts"],
        setupFiles: ["dotenv/config"],
      },
    };
  }

  return {
    test: {
      testTimeout: 30_000,
      exclude: ["**/*.int.test.ts", ...configDefaults.exclude],
    },
  };
});

向 package.json 添加脚本：

{
  "scripts": {
    "test": "vitest",
    "test:integration": "vitest --mode int"
  }
}

显式运行集成测试：

npm run test:integration

管理 API 密钥

集成测试需要真实 API 凭证。请从环境变量加载凭证，避免将密钥提交到源代码管理系统。将 dotenv/config 添加为 vitest 设置文件，使环境变量自动从 .env 加载：

vitest.config.ts

export default defineConfig({
  test: {
    setupFiles: ["dotenv/config"],
  },
});

.env

OPENAI_API_KEY=sk-...

缺少密钥时跳过测试：

import { test } from "vitest";

test.skipIf(!process.env.OPENAI_API_KEY)(
  "agent responds with tool call",
  async () => {
    // ...
  }
);

将 .env 添加到 .gitignore，避免提交凭证。在 CI 中，通过提供商的密钥管理机制注入 secrets，例如 GitHub Actions secrets。

断言结构，而不是内容

LLM 响应在不同运行之间会变化。请不要断言精确的输出字符串，而是验证响应的结构属性：消息类型、工具调用名称、参数形状和消息数量。

test("agent calls weather tool", async () => {
  const agent = createAgent({ model: "claude-sonnet-4-6", tools: [getWeather] });
  const result = await agent.invoke({
    messages: [new HumanMessage("What's the weather in SF?")]
  });

  const aiMsg = result.messages.find(
    (m) => AIMessage.isInstance(m) && m.tool_calls?.length
  );
  expect(aiMsg).toContainToolCall({ name: "get_weather" });
  expect(result.messages.at(-1)).toBeAIMessage();
});

此示例使用自定义测试匹配器。请参阅下方部分了解设置方式和完整匹配器参考。

如需更严格的执行轨迹断言，请使用 AgentEvals 评估器。它支持 unordered 和 superset 等模糊匹配模式。

使用自定义测试匹配器

langchain 提供了自定义 vitest 匹配器，用于提高结构断言的可读性，并在失败时生成清晰的错误消息。请在设置文件中注册一次，之后它们就能在每个 expect() 调用中使用。

设置

添加一个 vitest 设置文件，用 LangChain 匹配器扩展 expect：

vitest.setup.ts

import { langchainMatchers } from "@langchain/core/testing";

expect.extend(langchainMatchers);

在 vitest 配置中引用该文件：

vitest.config.ts

export default defineConfig({
  test: {
    setupFiles: ["vitest.setup.ts"],
  },
});

TypeScript 类型会自动包含，因此无需额外配置自动补全。

检查消息类型

每个消息类都有对应的匹配器：toBeHumanMessage()、toBeAIMessage()、toBeSystemMessage() 和 toBeToolMessage()。不传参数时只检查类型，也可以传入字符串以同时匹配内容：

const response = await agent.invoke({
  messages: [new HumanMessage("What's the weather?")]
});
const lastMessage = response.messages.at(-1);

expect(lastMessage).toBeAIMessage();
expect(lastMessage).toBeAIMessage("It's 72°F and sunny.");

传入对象可匹配特定字段：

expect(lastMessage).toBeAIMessage({ name: "weather-bot" });
expect(toolMsg).toBeToolMessage({ tool_call_id: "call_1" });

断言工具调用

以下三个匹配器可用于断言 AIMessage 上的工具调用：

const response = await agent.invoke({
  messages: [new HumanMessage("Weather in SF and NYC?")]
});
const aiMsg = response.messages.find(
  (m) => AIMessage.isInstance(m) && m.tool_calls?.length
);

// 检查是否存在特定工具调用，与顺序无关
expect(aiMsg).toHaveToolCalls([
  { name: "get_weather", args: { city: "San Francisco" } },
  { name: "get_weather", args: { city: "New York" } },
]);

// 只检查数量
expect(aiMsg).toHaveToolCallCount(2);

// 检查是否至少有一个工具调用匹配，支持 .not
expect(aiMsg).toContainToolCall({ name: "get_weather" });
expect(aiMsg).not.toContainToolCall({ name: "send_email" });

断言工具消息

toHaveToolMessages() 接收完整消息数组，并按顺序检查其中的 ToolMessage 实例：

expect(response.messages).toHaveToolMessages([
  { content: "72°F and sunny in San Francisco" },
  { content: "68°F and cloudy in New York" },
]);

断言中断和结构化响应

toHaveBeenInterrupted() 检查 LangGraph interrupt 结果中是否存在 __interrupt__ 字段。传入一个值可匹配中断载荷：

const result = await graph.invoke(input);

expect(result).toHaveBeenInterrupted();
expect(result).toHaveBeenInterrupted("confirm_action");

toHaveStructuredResponse() 检查结果中是否存在 structuredResponse 字段。传入对象可匹配特定字段：

expect(result).toHaveStructuredResponse();
expect(result).toHaveStructuredResponse({ name: "Alice", age: 30 });

匹配器参考

Matcher	描述
`toBeHumanMessage(expected?)`	检查值是否为 `HumanMessage`。可选择匹配内容（字符串）或字段（对象）。
`toBeAIMessage(expected?)`	检查值是否为 `AIMessage`。可选择匹配内容或字段。
`toBeSystemMessage(expected?)`	检查值是否为 `SystemMessage`。可选择匹配内容或字段。
`toBeToolMessage(expected?)`	检查值是否为 `ToolMessage`。可选择匹配内容或 `tool_call_id` 等字段。
`toHaveToolCalls(expected)`	检查 `AIMessage` 是否包含精确匹配的给定工具调用，与顺序无关。
`toHaveToolCallCount(n)`	检查 `AIMessage` 是否精确包含 `n` 个工具调用。
`toContainToolCall(expected)`	检查 `AIMessage` 是否包含至少一个匹配的工具调用。支持 `.not`。
`toHaveToolMessages(expected)`	检查消息数组是否按顺序包含给定的 `ToolMessage` 实例。
`toHaveBeenInterrupted(value?)`	检查结果是否包含 `__interrupt__`。可选择匹配中断值。
`toHaveStructuredResponse(expected?)`	检查结果是否包含 `structuredResponse`。可选择匹配特定字段。

降低成本和延迟

调用 LLM API 的集成测试会产生真实成本。以下做法有助于让测试套件保持快速且成本可控：

使用较小的模型：对于只需要验证工具调用和响应结构的测试，使用 gemini-3.1-flash-lite 或等效模型。
设置 maxTokens：限制响应长度，避免生成较长且昂贵的补全。
限制测试范围：每个测试只测试一种行为。如果单轮测试足够，请避免串联多次 LLM 调用的端到端场景。
选择性运行：使用上文中的测试分离方法，只在 CI 或部署前运行集成测试，而不是在每次保存文件时运行。

const agent = createAgent({
  model: "gemini-3.1-flash-lite",
  tools: [getWeather],
  modelArgs: { maxTokens: 256 },
});

后续步骤

了解如何在 Evals 中使用确定性匹配或 LLM-as-judge 评估器评估 Agent 执行轨迹。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

分离单元测试和集成测试

管理 API 密钥

断言结构，而不是内容

使用自定义测试匹配器

设置

检查消息类型

断言工具调用

断言工具消息

断言中断和结构化响应

匹配器参考

降低成本和延迟

后续步骤

​分离单元测试和集成测试

​管理 API 密钥

​断言结构，而不是内容

​使用自定义测试匹配器

​设置

​检查消息类型

​断言工具调用

​断言工具消息

​断言中断和结构化响应

​匹配器参考

​降低成本和延迟

​后续步骤

分离单元测试和集成测试

管理 API 密钥

断言结构，而不是内容

使用自定义测试匹配器

设置

检查消息类型

断言工具调用

断言工具消息

断言中断和结构化响应

匹配器参考

降低成本和延迟

后续步骤