集成测试

集成测试用于验证您的代理是否能与模型API和外部服务正确协作。与使用模拟对象和存根的单元测试不同，集成测试会进行实际的网络调用，以确认组件协同工作、凭证有效且延迟可接受。由于LLM响应具有不确定性，集成测试需要采用与传统软件测试不同的策略。本指南介绍如何为您的代理组织、编写和运行集成测试。关于为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中，通过您的提供商的密钥管理（例如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__ 字段。传递一个值以匹配中断负载：

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 });

匹配器参考

匹配器	描述
`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-preview 或同等模型。
设置 maxTokens：限制响应长度，以避免冗长且昂贵的补全。
限制测试范围：每个测试测试一种行为。当单轮测试足够时，避免链接多个LLM调用的端到端场景。
选择性运行：使用上述的测试分离方法，仅在CI或部署前运行集成测试，而不是在每次文件保存时运行。

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

后续步骤

了解如何在评估中使用确定性匹配或LLM作为评判的评估器来评估代理轨迹。

将这些文档连接到Claude、VSCode等，通过MCP获取实时答案。

在GitHub上编辑此页面或提交问题。

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Deploy with LangSmith

分离单元测试和集成测试

管理API密钥

断言结构而非内容

使用自定义测试匹配器

设置

检查消息类型

断言工具调用

断言工具消息

断言中断和结构化响应

匹配器参考

降低延迟和成本

后续步骤

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

​管理API密钥

​断言结构而非内容

​使用自定义测试匹配器

​设置

​检查消息类型

​断言工具调用

​断言工具消息

​断言中断和结构化响应

​匹配器参考

​降低延迟和成本

​后续步骤

分离单元测试和集成测试

管理API密钥

断言结构而非内容

使用自定义测试匹配器

设置

检查消息类型

断言工具调用

断言工具消息

断言中断和结构化响应

匹配器参考

降低延迟和成本

后续步骤