集成测试用于验证 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.