e2e中agent.waitFor与agent.extract使用场景全解析AI E2E 测试的两个关键判断【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2ee2e 是面向 Web 与移动端的下一代 AI E2E 测试框架。它内置agent智能体夹具让测试可以直接用自然语言描述屏幕上应该是什么样子。其中agent.waitFor等待条件成立和agent.extract结构化提取页面数据是与agent.assert并列的判断层API也是新手最容易用错的两个方法。本文将通过真实测试示例完整解析这两个 API 的使用场景、关键参数和常见坑位。一、先分清判断层三兄弟assert / waitFor / extracte2e 的agent刻意只保留少量方法分成两层执行层agent.act规划并执行一串操作填表单、点按钮判断层assert、waitFor、extract每次调用都是一次全新观察 明确的超时 受限的模型调用次数。判断层的核心设计是模型只看当前屏幕的证据不读之前步骤的总结所以结论可信、可回放。实现位于 agent/index.tsAPI 类型定义在 types.ts。方法一句话定位返回典型场景agent.assert立即判断一次当前屏幕通过 / 失败现在就应该如此的语义校验agent.waitFor轮询等待直到条件成立Promisevoid异步加载、进度条、延迟出现的元素agent.extract按 schema 读取结构化数据校验后的数据对象抓 KPI、订单金额、列表项判断层的完整语义请阅读官方文档 docs/assertions.mdx 与 docs/reference/agent.mdx。二、agent.waitFor 使用场景全解析该等的时候才等1. 异步加载替代固定 sleep 的最佳选择最典型的用例是点击后列表延迟出现。仓库内置测试 judgments.e2e.ts 就是标准示范test(waitFor polls until the loaded users appear, async ({ browser, agent, screen }) { await browser.goto(/network); await screen.getByRole(button, Load users).click(); await agent.waitFor(the list shows the three users Ada, Grace, and Margaret, { interval: 250, }); });用固定sleep的问题写短了测试偶发失败写长了拖慢整个套件。waitFor则是条件满足即刻返回天然消除这类不稳定性。2. 轮询机制屏幕不变就不花模型的钱这是waitFor最精妙的地方。它的执行循环见 waitForNextJudgment是调用模型判断一次条件是否成立若不成立先等一个interval默认 3000ms之后每 500ms 做一次纯引擎的观察不花模型调用比较屏幕是否变化只有屏幕真的变了才再发起一次模型判断。所以屏幕 2 秒前就变好了就约 2 秒后返回而不是傻等完整间隔转圈动画每秒都在变interval也会把判断频率压住防止烧光预算。3. 参数速查与调优技巧interval两次模型判断的最小间隔100~60000ms默认 3000ms。快速动画、倒计时调小到 500 甚至 100mstimeout总截止时间默认取 agent 配置的judgmentTimeout30s。慢导出、大数据量加载请显式调大maxModelCalls模型调用次数预算只可下调。官方文档中的慢操作示例docs/assertions.mdxawait agent.waitFor(the export finishes and a download link appears, { interval: 500, timeout: 120_000, });4. 超时不是裸报错会带上最后一次判断的解释waitFor超时会抛STEP_TIMEOUT且错误信息附带模型最后一轮的判断理由例如按钮一直显示禁用文案仍是 Exporting。排障时这比一个干巴巴的超时有价值得多——它直接告诉你屏幕卡在了哪一步。三、agent.extract 使用场景全解析把屏幕变成结构化数据1. 从半结构化页面提取数据当页面数据没有稳定选择器、或你不想为每个字段写死定位时extract让你用一句自然语言 一个 schema 直接拿到结构化对象。真实测试示例judgments.e2e.tsconst data await agent.extract(the todo titles and the remaining count, { schema: z.object({ todos: z.array(z.string()), remaining: z.number().int(), }), }); expect(data.remaining).toBe(1); expect(data.todos).toContain(Water the plants);提取到的对象随后可以无缝接上expect做精确断言——AI 负责读屏确定性断言负责把关。2. 它到底做了什么提取 校验 一轮修复执行逻辑见 agent.extract 实现取一次全新屏幕观察请求模型按found / value / missing的信封格式作答你的 schema 支持 JSON Schema 投影时如 Zod模型直接看到字段结构而不是靠猜返回值会经 schema 校验校验失败会进行一次修复重试预算固定为 2 次模型调用。3. 两个关键错误它宁可失败也不给你假数据屏幕上看不到数据抛ASSERTION_INCONCLUSIVE并说明缺什么。框架明确拒绝返回或0之类的占位符修复后仍不合法抛MODEL_OUTPUT_INVALID。如果你确实接受字段可能不存在请在 instruction 和 schema 里都写明例如the phone number, or null when none is shown配z.string().nullable()。4. 三个高价值场景仪表盘 KPI 快照抓取工作区名称 套餐这类组合信息docs/reference/agent.mdx 的示例金额与合计校验提取订单明细与总额再在测试里验证数学关系探索模式的内部引擎e2e 的 explore 功能正是用extract让模型按PLAN_SCHEMA产出探索计划explore/plan.ts可见它是框架级的数据通道。四、何时用哪个一张表说清需求推荐做法理由校验精确文本、精确值expect 定位器断言零模型调用最快最稳语义级现在应该如此agent.assert一次判断立即给结论条件稍后才成立agent.waitFor智能轮询省模型调用需要数据对象继续断言agent.extract结构化输出 schema 校验答案只在像素里canvas 图表、布局遮挡三者加vision: true或only模型可读取遮罩截图两条新手须知缓存与回放act等步骤可被步骤缓存复用而assert/waitFor/extract永远实时执行保证验证不被回放蒙混过关见 docs/cache.mdx隐私保护一旦测试中填充过密码等敏感值后续步骤的截图证据会被自动收回vision模式可能降级或拒绝属预期行为。五、总结记住这三句话agent.waitFor 聪明的等待条件描述写清楚成立的标准interval控制节奏超时信息自带最后判断理由agent.extract 带校验的读屏Zod schema 决定返回结构拿不到数据会明确报错而不是编造精确值用expect语义才交给 AI这样既享受 AI 的灵活性又保住 E2E 测试的确定性。【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考