AI Agent / 系统课时
为节点与路由编写自动测试
为节点与路由编写自动测试
这一节把智能体图拆成可稳定断言的三层:纯节点、条件路由和关键图路径。目标不是测试 LangGraph 框架本身,而是固定输入状态,验证节点更新、路由决策以及真实下一跳,从而让工作流修改后能快速发现行为回归。
学习目标
- 直接调用纯节点并断言其状态增量,不经过整张图
- 对条件路由函数做参数化测试,覆盖主要分支
- 通过图的更新事件断言关键路径实际经过的节点与最终更新
把测试分成三个层次
纯节点测试成本最低,适合验证状态转换规则;路由测试只关心输入状态会返回哪个分支标签;图路径测试最后再确认边和节点连接正确。这样失败时能快速判断是业务函数、分支判断还是图装配出了问题。
不要一上来只写端到端测试。端到端失败通常只能告诉你“结果不对”,却很难定位是哪一个节点或条件边导致了偏差。相反,节点和路由保持纯函数形态后,大部分逻辑都可以在毫秒级完成测试。
准备一个可测试的小图
下面两个文件构成一个完整测试示例。workflow.py 定义状态、纯节点、路由函数与图装配;它本身不发起模型调用,也不访问外部服务,因此测试结果是确定的。
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 或实现细节。
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 后,在两个文件所在目录运行:
pytest -q预期输出
5 passed in <TIME>s<TIME> 是动态耗时,机器不同会变化。这里有 5 个测试用例,是因为两个参数化测试分别展开成 2 个用例。
让断言对重构保持稳定
节点单测优先断言“这个节点负责写出的增量”,不要要求它返回整个全局状态;否则只要状态模型增加一个无关字段,测试就会被迫跟着修改。路由测试则应直接调用路由函数,明确覆盖每个关键分支和边界输入。
图路径测试适合断言业务可观察行为,例如访问了 normalize 后进入 vip,并得到 handled_by=vip_queue。不要断言运行 ID、checkpoint ID、内部任务对象或事件中与业务无关的元数据,这些都属于容易变化的实现细节。
如果节点内部必须调用 LLM、HTTP 或数据库,把这些依赖通过参数、闭包或可替换客户端隔离出去,在节点测试里使用 fake 或 mock。真正访问外部系统的测试留到少量集成测试中,否则网络波动、模型随机性和测试数据变化会把单元测试变成不稳定报警器。
失败时按层次定位
节点测试失败,先检查状态转换逻辑;路由测试失败,检查分支条件与返回标签;两者都通过但图路径失败,再检查 add_conditional_edges 的标签映射和边连接。按照这个顺序定位,能把“智能体走错路”从一个模糊现象拆成可重复、可修复的具体回归。