为什么e2e的act步骤可缓存而assert必须实时？设计原理剖析-开发者社区

为什么e2e的act步骤可缓存而assert必须实时？设计原理剖析

【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e

e2e 是一个面向 Web 和移动应用的下一代端到端测试框架：用自然语言描述目标，AI 智能体（agent）就会驱动应用去完成它。在 e2e 中，agent.act()步骤支持回放缓存——录制一次后，后续运行零模型调用直接重放；而agent.assert()则永远实时执行。这种不对称不是偶然，而是深思熟虑的设计。本文带你从新手视角剖析其背后的原理。

先搞清楚：e2e 的两种 agent 步骤

在 e2e 里，一个测试通常长这样：先让 agent 做事（act），再检查做对了没有（assert / expect）。

agent.act()（行动步骤）：驱动应用完成操作——点击、输入、导航。它会改变应用状态，比如"把工作区升级到 Pro 计划"。
agent.assert()（断言步骤）：判断当前屏幕是否满足某条件，比如"发票预览显示按比例计费金额"。它是只读的，绝不能改变应用状态。

这个"一个动手、一个看结果"的分工，正是缓存设计差异的根源。

e2e 的 act 步骤回放缓存是怎么工作的

官方文档 docs/cache.mdx 描述的完整生命周期分四步：

录制：首次运行时，agent 用模型逐步操作应用，每一步动作（点了哪个控件、输入了什么值）被记录成一条"录制"（recording）。
确认：act结束后不会立刻写盘。只有当后续的验证步骤通过（如agent.assert或expect(...)断言），录制才在尝试（attempt）结束时被正式写入.e2e/cache/目录。
重放：下次运行时，框架按缓存条目重放动作——匹配路由、逐个找回控件并重复操作、再核对最终状态。全程零模型调用。
自愈：如果控件找不到、或最终状态没复现出来，重放会中途"移交"（hand-off）给 agent，从当前屏幕继续执行并自动重新录制。

运行结束后，报告里会看到类似这样的摘要：

AI 4.1k tokens · 2 model calls Cache 4 replayed · 1 handed off · 1 missed

为什么只有 act 可缓存：三条设计原理

原理一：assert 的本质是"测量当下"，结果无法预先存储

agent.assert回答的问题是"此刻的屏幕上是不是出现了 X"。答案完全取决于应用当下的状态——数据可能刚被修改、横幅可能刚弹出来、倒计时可能刚结束。

如果把上次运行得到的"通过"结论缓存起来，下次测试就会"闭着眼"通过：断言根本没看一眼屏幕，就宣称一切正常。那断言就失去了存在的意义。判断类步骤唯一正确的做法，就是现在看、现在判。

原理二：assert 正是 act 录制的"验收人"

这是最精妙的一点。e2e 的缓存写入有一个前提：后续验证步骤必须通过。源码注释（packages/e2e/src/agent/act.ts）写得直白：

An assert is a verification step: its passing is what confirms the traces staged before it at attempt end.

也就是说，act的录制先被"暂存"（staged），要靠后面assert的实时通过来盖章确认，才允许写入缓存。两条因果链在这里咬合：

assert的判定是act录制是否可信的依据；
如果assert的判定本身也能来自缓存，那么一个过期的"通过"就会永远确认一条可能早已失效的录制——缓存变成自洽闭环，错误永远无人发现。

所以assert必须实时，它是整个缓存体系的信任锚点。

原理三：assert 不改变状态，本来就没有"动作"可录

回放缓存的对象是动作序列（点了什么、填了什么）。而assert一个操作都不做，它的"动作轨迹"天然为空——重放一段空轨迹毫无意义，连查一次缓存都嫌浪费。源码在 packages/e2e/src/agent/act.ts 中直接写死了这个规则：

// Only act steps are cacheable: an assert must not change state, so its // trace would be empty — nothing to replay, nothing worth a read. const cache = spec.kind === 'act' && agent.executor.cache !== 'off' ? runtime.cache : undefined;

同理，agent.waitFor和agent.extract也永远实时执行（见 docs/cache.mdx 开头一句：agent.assert、agent.waitFor和agent.extractalways run live）。

缓存的安全网：应用变了会怎样

既然缓存的是"过去成功的操作序列"，应用一变怎么办？e2e 的答案是宁可慢，不可错：

路由不匹配（wrong-context）：起点页面变了，缓存不生效，agent 从头执行。
找不到控件（target-not-found）：UI 改版了，等待 15 秒仍找不到则移交 agent，下次通过的运行会重新录制。
end-mismatch：所有动作都重放成功，但录制里"应该出现的控件"没出现——说明录制已不能产出预期效果。这条录制会被驱逐（evict），下次运行录一条干净的新流程。
cache.strict模式：已提交的录制失效时直接以REPLAY_STALE报错、拒绝静默重录，强迫团队显式地重新录制并提交变更。

所有缓存决策（暂存、保留、驱逐）都集中在 packages/e2e/src/agent/step-cache.ts 的StepTraceSession类中，conclude()方法里的注释把"什么情况下保留、什么情况下删除"写得清清楚楚。

新手最佳实践：三步用好回放缓存

每个act后面紧跟一次验证——agent.assert(...)或expect(screen.getByRole(...))。没有验证，录制不会被确认，缓存就永远建不起来。
每次运行都变化的值（时间戳、随机邮箱）用unique()包裹，这样重放时会自动替换为当前值，不会因为数据不同而每次都缓存未命中。
把.e2e/cache/提交进仓库共享重放，CI 默认保持只读（read-only），本地开发用read-write负责重新录制。

一个完整的示例项目可以直接参考：examples/with-next/，下面是它的运行截图。