
写好智能体测试的 5 条原则:从用户意图到可诊断失败
从用户意图而非实现细节出发,用结果等待替代固定休眠,以独立事实源做精确断言,并通过隔离数据与失败追踪让端到端测试真正可信。
一套好的端到端测试很像一辆保养良好的汽车。你知道它在最需要的时候不会掉链子。没有人会开着一辆自己并不信任的车去公路旅行。
测试也是一样。你需要一套可以依赖的端到端测试:改完代码,测试全部通过,你就能确信刚刚验证过的用户流程仍然可用。这正是端到端测试的意义。
一旦团队不再信任测试套件,它就会开始腐化。红色的构建结果被反复重跑,而不是被认真阅读;失败的测试被以“暂时”为理由跳过。几个月后,已经没人记得其中一半测试到底在检查什么。
智能体测试使用 AI 智能体在应用中执行用户流程。用于自动化的 UI 测试时,工程师描述关键业务流程,智能体自行判断需要完成哪些交互。但究竟要断言什么、什么才算成功,仍然必须由工程师决定。
本文介绍编写可维护智能体端到端测试的五种方法,示例使用 e2e。贯穿全文的例子是一个项目管理应用:用户在其中生成月度活动报告。
不要测试实现细节
用户只想生成一份月度报告。他们不关心日期选择器使用的是 Material UI 组件,也不关心“生成”按钮内部嵌套了多少层元素。
绑定这些细节的测试会在实现变化时失败,即使用户依然能够完成整条流程。
大多数指南会建议使用稳定、面向用户的定位器。这条建议当然有用,但智能体测试还能再向前一步:直接围绕用户意图定义测试。
用户不知道什么是测试 ID,他们甚至根本看不到它。
在示例中,测试使用上个月的报告,并在每次运行时准备相匹配的测试数据。这样即使月份不断变化,测试套件仍然有意义。
使用 agent.act 时,你描述一个目标,再让智能体自行判断要执行哪些动作:
await agent.act("Generate last month's activity report");
智能体可以自行判断它需要选择月份、输入两个日期,还是选择一个预设选项。它也不需要知道应用使用的是 shadcn/ui、Bootstrap 还是 Material UI。用户同样不关心这些。
不过,生成报告只完成了测试的一半。你还需要断言来证明报告确实生成,并且内容反映的是正确数据。空报告是缺陷,包含错误记录的报告同样是缺陷。
await agent.assert(`The report shows ${expectedTasks.length} completed tasks`);
await agent.assert(
`The report contains exactly these task records, with no additional tasks: ${JSON.stringify(expectedTasks)}`,
);
现在,报告会与实际活动数据进行对照。当数据源中存在任务时,空报告会失败;任务数量正确但记录错误也会失败,包括混入了另一个工作区的任务。预期数据必须从底层活动数据源独立读取,而不能从正在被测试的报告中读取。
智能体测试还需要足够具体的目标。像“测试报告”这样的目标留下了太多解释空间;生成一份特定报告则提供了一个可以检查的明确结果。
等待结果,减少不稳定测试
加入五秒休眠,很容易让一个不稳定的测试在你的机器上通过。它也很容易让每一次成功运行都多花五秒。等待时间很快就会累积起来。
报告生成就是一个很好的例子。根据数据量和服务器当前负载,同一个操作在每次运行中都可能花费不同时间。
不要加入任意延迟,而应该等待结果出现:
await agent.waitFor("Last month's activity report is ready to view", {
timeout: 15_000,
});
agent.waitFor 会检查一个条件,并在超时预算和模型调用预算之内等待条件变为真。超时时间是一条上限,而不是必须等满的时长。条件成立后,测试很快就会继续执行。
好的等待条件应该代表下一步已经就绪。等待加载指示器消失或许“能用”,但它并不是一个很强的信号。检查报告本身已经可用,可以提供更有力的证据。
这里有一个重要的 API 细节:agent.assert 会立即检查当前屏幕,不会等待。当应用需要时间才能到达目标状态时,应使用 agent.waitFor。
你也可以使用 expect.poll 等待某个值。agent.waitFor 通过 AI 判断屏幕是否符合描述;expect.poll 则会反复执行确定性的匹配器,直到它通过或超时。
让断言足够具体
点击“生成”是一个动作,得到一份包含正确数据的报告才是结果。只执行动作的测试会漏掉最有价值的部分,因此必须定义要断言的状态。
使用 API 响应中的数量或其他事实来源作为预期值。报告打开后,断言这个结果:
await agent.assert(
`The report covers last month and shows ${expectedTasks.length} completed tasks`,
);
断言必须精确。像“报告看起来正确”这样的表述,只会迫使智能体猜测什么叫“正确”。
使用 agent.assert 时,裁判会评估当前屏幕上的最新证据。判断为假或无法得出结论时,测试都会失败。执行动作的智能体声称任务已经完成,并不足以证明成功。
还要考虑每条断言究竟证明了多少事情。“报告已就绪”的消息只能证明应用到达了这个状态,不能证明报告包含正确信息。检查页面预览,也不能证明下载得到的 CSV 具有相同内容。
对于每一个有意义的动作,都要识别出那个足以让你相信它成功的可观察结果,并把这项检查写进测试。
保持测试聚焦且相互独立
报告测试不应该依赖“完成一个任务”的测试先运行。
当整套测试始终按照某个固定顺序运行时,这种依赖看起来也许能够工作。但单独运行报告测试、重试它,或者并行运行测试时,它依赖的数据可能突然消失。
每个测试都应该自行准备所需状态。对于报告示例,这意味着准备一个包含已知任务和完成日期的工作区。另一个测试在同一工作区完成任务时,不应该改变 API 读取数据与生成报告之间的数据状态。
良好的测试数据管理还包括清理。可以使用 afterEach 在每个测试后清理,或使用 afterAll 清理属于整个套件的数据。钩子里要做什么,取决于测试创建了什么。如果测试通过 API 创建了工作区,就通过 API 删除它;如果测试直接向数据库插入了记录,就删除这些记录。下一个测试应该得到它预期的状态,而不是上一次运行留下的残余。
e2e 提供了 app、agent 和 screen 等 fixture。你也可以使用 test.extend 定义自己的 fixture,例如一个已经填充报告数据的工作区,并在多个测试套件中复用它。
如果共享代码能够保持重要行为的一致性,它仍然有价值。把共享放在真正能让测试更容易理解和维护的地方。
让失败易于诊断
发现缺陷是好事。但一个只写着“something went wrong”的红色 CI 任务,基本上是在邀请你花一下午排查问题。
从能够描述预期行为的测试名称开始。“月度活动报告包含工作区中已完成的任务”比“报告测试”提供更多上下文。测试失败时,名称本身就应该说明哪项行为出了问题。
把生成报告、下载报告和把报告发送给同事拆成独立测试,每个测试都有自己的设置和具体名称。在每个测试内部,让智能体目标足够小、可以分别检查,从而保证调试日志容易阅读。
调试日志应该说明什么失败了以及为什么失败:智能体尝试做什么、它期待什么、实际又发生了什么。失败的智能体断言可以提供这类信息。例如,它可以说明测试要求的是上个月,但页面显示的却是当前月份。
e2e 的失败追踪会补充通向失败的步骤、应用日志、最近的智能体回合,以及在可用时加入截图和屏幕快照。这些证据既可供人类分析,也可供编码智能体推理。
失败追踪不能保证完美复现问题,也不能自动指出应用代码中的故障行。但清晰的目标、明确的预期和观察到的结果,仍然是更好的调查起点。
挑一个团队目前还在手工执行的流程,用这种方式把它写成测试。失败时,你应该能够说清用户想做什么、实际发生了什么,以及从哪里开始调查。
一个完整的 e2e 端到端测试
如果你以前写过测试,可能已经熟悉“准备、执行、断言”模式:准备所需状态,执行动作,再检查结果。智能体测试遵循同样的结构。你仍然决定测试从哪里开始、什么算成功,只是由智能体判断如何执行动作。
下面是把五项实践全部用上的完整月度报告测试:
test("Monthly activity report includes the workspace's completed tasks", async ({
app,
agent,
reportWorkspace,
}) => {
// Arrange
const expectedTasks = await getCompletedTasks(reportWorkspace.id, "last month");
await app.open(`/workspaces/${reportWorkspace.id}/reports`);
// Act
await agent.act("Generate last month's activity report");
await agent.waitFor("Last month's activity report is open", { timeout: 15_000 });
// Assert
await agent.assert(
`The report covers last month and shows ${expectedTasks.length} completed tasks`,
);
await agent.assert(
`The report contains exactly these task records, with no additional tasks: ${JSON.stringify(expectedTasks)}`,
);
});
这里,reportWorkspace 是一个 fixture。getCompletedTasks 通过应用 API 读取当前工作区的活动数据。智能体负责生成报告,waitFor 等待报告打开,断言则把报告内容与独立的事实来源进行比较。
下一步做什么
测试套件是通过一个个有用结果逐步赢得信任的。描述用户想做什么,等待应用就绪,再检查结果是否真的符合预期。智能体测试让工程师有更多空间专注这些决定,但不会替工程师做决定。
从团队反复重跑的那个测试开始。检查它试图证明什么、它在等待什么,以及什么情况应当使它失败。先修好这一条,再处理下一条。你不需要重写整套测试,才能让它重新变得有用。
如果想在自己的应用中尝试这套流程,可以从 e2e 快速入门开始,选择一个流程,然后故意破坏一项功能,看看测试能否抓住它。
原文来源:《5 tips for writing good agentic tests with e2e》,作者 Kacper Kapuściak,发布于 2026 年 11 月 13 日。