AI Agent / 系统课时

为节点与路由编写自动测试

为节点与路由编写自动测试

这一节把智能体图拆成可稳定断言的三层:纯节点、条件路由和关键图路径。目标不是测试 LangGraph 框架本身,而是固定输入状态,验证节点更新、路由决策以及真实下一跳,从而让工作流修改后能快速发现行为回归。

学习目标

  • 直接调用纯节点并断言其状态增量,不经过整张图
  • 对条件路由函数做参数化测试,覆盖主要分支
  • 通过图的更新事件断言关键路径实际经过的节点与最终更新

把测试分成三个层次

纯节点测试成本最低,适合验证状态转换规则;路由测试只关心输入状态会返回哪个分支标签;图路径测试最后再确认边和节点连接正确。这样失败时能快速判断是业务函数、分支判断还是图装配出了问题。

不要一上来只写端到端测试。端到端失败通常只能告诉你“结果不对”,却很难定位是哪一个节点或条件边导致了偏差。相反,节点和路由保持纯函数形态后,大部分逻辑都可以在毫秒级完成测试。

准备一个可测试的小图

下面两个文件构成一个完整测试示例。workflow.py 定义状态、纯节点、路由函数与图装配;它本身不发起模型调用,也不访问外部服务,因此测试结果是确定的。

python
from __future__ import annotations

from typing import Literal, NotRequired, TypedDict

from langgraph.graph import END, START, StateGraph

class TicketState(TypedDict):
    priority: str
    normalized: NotRequired[str]
    handled_by: NotRequired[str]

def normalize_node(state: TicketState) -> dict:
    return {"normalized": state["priority"].strip().lower()}

def route_priority(state: TicketState) -> Literal["vip", "normal"]:
    return "vip" if state["normalized"] in {"p0", "p1"} else "normal"

def vip_node(state: TicketState) -> dict:
    return {"handled_by": "vip_queue"}

def normal_node(state: TicketState) -> dict:
    return {"handled_by": "normal_queue"}

def build_graph():
    builder = StateGraph(TicketState)
    builder.add_node("normalize", normalize_node)
    builder.add_node("vip", vip_node)
    builder.add_node("normal", normal_node)
    builder.add_edge(START, "normalize")
    builder.add_conditional_edges(
        "normalize",
        route_priority,
        {"vip": "vip", "normal": "normal"},
    )
    builder.add_edge("vip", END)
    builder.add_edge("normal", END)
    return builder.compile()

编写节点、路由与图路径测试

test_workflow.py 先直接调用 normalize_node,再参数化测试 route_priority,最后用 stream_mode="updates" 观察每一步由哪个节点产生更新。图路径断言的是节点名称和关键状态增量,而不是内部 checkpoint ID 或实现细节。

python
import pytest

from workflow import build_graph, normalize_node, route_priority

def test_normalize_node_returns_only_its_update():
    update = normalize_node({"priority": " P1 "})
    assert update == {"normalized": "p1"}

@pytest.mark.parametrize(
    ("normalized", "expected"),
    [("p0", "vip"), ("p3", "normal")],
)
def test_route_priority(normalized, expected):
    state = {"priority": normalized, "normalized": normalized}
    assert route_priority(state) == expected

@pytest.mark.parametrize(
    ("priority", "expected_node", "expected_queue"),
    [("P1", "vip", "vip_queue"), ("P3", "normal", "normal_queue")],
)
def test_graph_takes_expected_path(priority, expected_node, expected_queue):
    graph = build_graph()
    events = list(
        graph.stream(
            {"priority": priority},
            stream_mode="updates",
        )
    )

    visited = [next(iter(event)) for event in events]
    assert visited == ["normalize", expected_node]
    assert events[-1][expected_node]["handled_by"] == expected_queue

安装好 langgraph 与 pytest 后,在两个文件所在目录运行:

bash
pytest -q

预期输出

text
5 passed in <TIME>s

<TIME> 是动态耗时,机器不同会变化。这里有 5 个测试用例,是因为两个参数化测试分别展开成 2 个用例。

让断言对重构保持稳定

节点单测优先断言“这个节点负责写出的增量”,不要要求它返回整个全局状态;否则只要状态模型增加一个无关字段,测试就会被迫跟着修改。路由测试则应直接调用路由函数,明确覆盖每个关键分支和边界输入。

图路径测试适合断言业务可观察行为,例如访问了 normalize 后进入 vip,并得到 handled_by=vip_queue。不要断言运行 ID、checkpoint ID、内部任务对象或事件中与业务无关的元数据,这些都属于容易变化的实现细节。

如果节点内部必须调用 LLM、HTTP 或数据库,把这些依赖通过参数、闭包或可替换客户端隔离出去,在节点测试里使用 fake 或 mock。真正访问外部系统的测试留到少量集成测试中,否则网络波动、模型随机性和测试数据变化会把单元测试变成不稳定报警器。

失败时按层次定位

节点测试失败,先检查状态转换逻辑;路由测试失败,检查分支条件与返回标签;两者都通过但图路径失败,再检查 add_conditional_edges 的标签映射和边连接。按照这个顺序定位,能把“智能体走错路”从一个模糊现象拆成可重复、可修复的具体回归。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为节点与路由编写自动测试

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通