一、整图测试：最基础的冒烟验证

整图测试是入门级测试，解决的核心问题只有一个：这个图从头跑到尾，能不能正常执行完，最终结果对不对？

核心思路

每个测试用例完全独立：

重新创建 graph 实例
重新创建全新的 checkpointer
调用 invoke 跑完整个流程
断言最终的 state 是否符合预期

最关键的原则（90%的人踩过坑）

绝对不要在多个测试用例之间共享 graph 实例或 checkpointer 实例

原因非常简单：

graph 本身带有内部执行状态
checkpointer 会保存所有执行记录和 checkpoint
一旦共享，前一个测试的残留数据会污染后一个测试，导致结果飘忽不定

哪怕两个测试用的是完全一样的图结构，也要每个 test 都重新 new 一份。

代码示例

import { StateGraph, START, END } from "@langchain/langgraph";
import { MemorySaver } from "@langchain/langgraph/checkpoint";
import { expect, test } from "vitest";

// 定义状态类型
type State = { input: string; processed: string; result: string };

// 构建图的工厂函数（每个测试用例调用一次）
const buildTestGraph = () => {
  const graph = new StateGraph<State>({
    channels: { input: null, processed: null, result: null },
  })
    .addNode("process", async (state) => ({
      processed: state.input.toUpperCase(),
    }))
    .addNode("finalize", async (state) => ({
      result: `[Final] ${state.processed}`,
    }))
    .addEdge(START, "process")
    .addEdge("process", "finalize")
    .addEdge("finalize", END);

  // 每个实例都有自己独立的 MemorySaver
  return graph.compile({ checkpointer: new MemorySaver() });
};

test("整图应该正确处理输入并生成最终结果", async () => {
  // ✅ 每个测试用例创建全新的图和 checkpointer
  const graph = buildTestGraph();
  const finalState = await graph.invoke({ input: "hello world" });

  expect(finalState.result).toBe("[Final] HELLO WORLD");
});

二、单节点测试：精准验证复杂逻辑

当你的某个节点逻辑特别复杂（比如包含 LLM 调用、数据处理、条件判断），或者它本身就是一个纯函数时，没必要每次都跑完整张图。这时候就该用单节点测试。

核心做法

LangGraph 编译完成后，所有节点都会暴露在 compiledGraph.nodes 对象上。你可以直接取出任意一个节点，像调用普通函数一样调用它的 invoke 方法。

最容易被忽略的关键点

直接调用节点不会触发任何 checkpoint 操作

也就是说：

单节点测试本质是纯逻辑测试
和整个图的流程、持久化、中断恢复完全无关
你只需要关注“给定输入，输出是否正确”

这一点一定要拎清楚，否则很容易产生误解，以为单节点测试会修改 checkpoint。

代码示例

test("单独测试 process 节点的文本转换逻辑", async () => {
  const graph = buildTestGraph();
  // 从编译后的图中直接取出节点
  const processNode = graph.nodes.process;

  // 像普通函数一样调用，只传需要的状态
  const result = await processNode.invoke({ input: "test input" });

  // 只断言这个节点的输出
  expect(result.processed).toBe("TEST INPUT");
  // ✅ 这里不会产生任何 checkpoint 数据
});

三、部分执行测试：复杂流程的终极测试方案

前两种测试都比较好理解，但真实项目中我们经常遇到这种情况：

图已经非常复杂，有十几个节点
你只想测试中间的某一小段流程
为了测试这一段，每次都要从头跑到尾，浪费大量时间
不想为了测试强行把流程拆成子图

这时候 LangGraph 的部分执行测试就是你的救星，它也是最能体现 LangGraph 工程化能力的测试方式。

核心思想

一句话概括：通过 checkpoint 模拟“存档”，直接从流程中间开始测试。

就像玩游戏时，你不用每次都从第一关开始打，直接加载打到第5关的存档，只测试第6关就行。

具体步骤

构造存档：使用 updateState 方法人工构造一个状态，并明确指定这个状态“相当于哪个节点刚刚执行完”
继续执行：使用同一个 thread_id 再次调用 invoke，流程会从你指定的节点之后继续往下跑
精准中断：可以通过 interruptAfter 参数，让流程在你想要的节点停下来，断言中间状态

代码示例

假设我们只想测试上面例子中的 finalize 节点，以及它之后的流程：

test("只测试从 process 节点之后到 finalize 节点的流程", async () => {
  const graph = buildTestGraph();
  const threadId = "test-partial-exec-1";

  // 1. 人工构造存档：模拟 process 节点已经执行完成
  await graph.updateState(
    { configurable: { thread_id: threadId } },
    { processed: "HELLO FROM ARCHIVE" }, // process 执行后的状态
    "process" // 关键：指定这个状态是 process 节点执行完的结果
  );

  // 2. 从存档位置继续执行，跑到 finalize 节点后就中断
  const result = await graph.invoke(
    {}, // 不需要新的输入
    {
      configurable: { thread_id: threadId },
      interruptAfter: ["finalize"], // 执行完 finalize 就停下来
    }
  );

  // 断言 finalize 节点的输出
  expect(result.result).toBe("[Final] HELLO FROM ARCHIVE");
});

这种方式的强大之处

完全不用关心前面的节点逻辑，只聚焦你要测试的部分
可以模拟任何中间状态，包括异常状态和边界情况
特别适合测试包含人工介入（interrupt）的流程
对于中大型 LangGraph 项目，能把测试速度提升一个数量级

总结：三种测试方式对比与最佳实践

适用场景对比表

测试方式	核心用途	优势	注意事项
整图测试	端到端冒烟测试、简单流程验证	最全面，验证整个流程的正确性	每个用例必须创建全新的实例
单节点测试	复杂逻辑节点、纯函数节点	速度极快，专注单个逻辑单元	不触发 checkpoint，只测纯逻辑
部分执行测试	中大型流程、中间段验证、含中断的流程	不用从头跑，精准定位问题	必须使用同一个 thread_id

我的最佳实践建议

优先写单节点测试：把所有复杂逻辑都抽成独立节点，用单节点测试覆盖所有边界情况，保证每个单元正确
用整图测试做冒烟：只写少数几个核心用例，验证整个流程能跑通，不用覆盖所有分支
复杂流程用部分执行：对于超过5个节点的流程，尽量用部分执行测试来验证中间段，避免每次都跑全流程
永远保持测试隔离：不要共享任何 graph 或 checkpointer 实例，这是避免测试玄学问题的根本

LangGraph 测试三大层级