e2e定位器Locators深入指南role、test id与智能体定位怎么选【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2ee2e 是一个面向 Web 和移动端的下一代 E2E 测试框架用自然语言描述目标AI 智能体Agent驱动应用达成它再用**定位器Locators**精确校验结果。这篇指南带你彻底搞懂三种定位方式——role 定位、test id 定位与智能体定位——分别在什么场景下最稳、最省让新手也能一步选对。什么是定位器为什么它不调用 AI在 e2e 中screen提供了一组语义化查询方法它们返回的是一个惰性定位器Locator查询本身不触发任何工作只有执行动作、读取或断言时才会真正解析节点。这也是 e2e 的定位器与智能体的根本分工——定位器是确定性的、零模型调用的而智能体才负责看懂屏幕。await screen.getByRole(button, Sign in).tap(); await screen.getByLabel(Email).fill(adaexample.test); await screen.getByTestId(todo).first().tap();定位器引擎负责三件事查询轮询0 匹配时等待到超时、严格性检查多个匹配立即报LOCATOR_AMBIGUOUS、动作重试节点过期会自动重解析。实现分别位于 screen.ts、engine.ts 与查询表达式构建 expression.ts官方入门文档见 docs/locators.mdx。三种查询怎么选role 优先、label 次之、test id 兜底e2e 的查询优先级写得很明确role 加名称第一label 第二test id 最后。完整查询清单参考 docs/reference/screen.mdx。1️⃣ role 定位语义最稳首选getByRole(role, name)按可访问性角色 名称查找元素。它的最大优点是跨平台Web 引擎按 HTML-AAM 从 HTML 推导角色移动端引擎把平台控件映射到同一套角色词表60 余种角色所以同一条 role 查询在浏览器和真机上读起来一模一样。它还支持状态过滤如getByRole(button, Save, { disabled: true })支持checked、selected、expanded、level标题级别等选项。字符串默认全词、区分大小写匹配加{ exact: false }变为不区分大小写的子串匹配也可以传正则。2️⃣ label 定位表单输入框的利器getByLabel(Email)按表单控件的可访问标签查找是填写表单输入框最自然的方式。同类还有getByPlaceholder、getByText、getByDisplayValue。两个实用细节回声文本getByText只回答最内层的匹配节点容器回显子节点文本不会算两次匹配隐藏副本框架常在文档里保留隐藏副本关闭的抽屉、未激活的 Tab所有查询都支持{ visible: true }在恰好一个规则生效前剔除隐藏节点避免误报LOCATOR_AMBIGUOUS。3️⃣ test id 定位最不容易碎但要先埋点getByTestId(todo-3)匹配节点的测试 IDWeb 上默认读取data-testid属性可用web({ testIdAttribute })改属性名见 packages/web/src/engine.ts设备上则是无障碍标识符或资源 id。字符串全词、区分大小写匹配也支持正则如/total-budgeted$/。test id 对文案改版免疫适合关键节点但它要求你在源码里埋点且对使用者不透明所以只作为兜底手段。精确到唯一缩小范围的四件工具当查询命中多个节点时动作和断言会立即报LOCATOR_AMBIGUOUS。e2e 提供四种收窄方式它们都返回新定位器、不查询应用方法用途示例.filter({ hasText })按子树文本子串不区分大小写过滤getByRole(listitem).filter({ hasText: Invoice 42 }).filter({ has })保留子树中能解析出内部定位器的匹配filter({ has: screen.getByRole(button, Void) }).first()/.last()取第一个 / 最后一个匹配getByRole(row).first().nth(i)取第 i 个匹配从 0 开始getByRole(option).nth(2)典型写法是先圈定一行、再在行内取按钮——像真实用户一样分层操作const row screen.getByRole(listitem).filter({ hasText: Design review }); await row.getByRole(button, Archive).tap();另外记住一个行为差异动作和断言会轮询等待直到通过或超时而textContent()、count()这类直接读取不等待、立即返回当前值。智能体定位让 AI 按目标找元素当 UI 没有稳定语义、或你不想逐元素写脚本时e2e 的智能体接管定位工作。agent.act接收一句自然语言指令模型读取语义树屏幕节点的脱敏序列化规划并执行动作树上没列出的控件如画布则自动请求截图用像素工具tap_at({ x, y })、type_at等按坐标操作。详见 docs/reference/agent.mdx。const { summary, cache } await agent.act(upgrade the workspace to the Pro plan); await expect(screen.getByRole(status)).toContainText(Pro);智能体定位的核心优势免脚本改 UI 不用改定位器用一句话描述目标即可回放缓存act步骤一旦通过了后续的expect断言其动作轨迹会被记录下次运行直接回放、零模型调用直到应用变化见 docs/cache.mdx安全兜底模型填入的值必须来自你的代码参数密码只会进入密码字段秘密值填充后截图立即停用PIXEL_TAINTED敏感数据不会外泄。智能体观察树的脱敏与预算控制在 observation.ts 中实现。决策速查三种定位方式一张表维度role 定位test id 定位智能体定位稳定性⭐⭐⭐ 语义不变就稳定⭐⭐⭐⭐ 对文案免疫⭐⭐⭐ 依赖 AI 判断成本零模型调用零模型调用首次消耗模型调用回放后免费适用按钮、链接、标题等语义控件关键节点、无语义元素画布/复杂交互、不想维护脚本维护成本随语义重构需埋点最低失败诊断精确报错LOCATOR_NOT_FOUND 等精确报错AgentError 带原因码与截图推荐组合拳能用 role 就用 role表单用 label关键且无语义的节点埋 test id探索性流程或复杂交互交给agent.act再用定位器加断言精确收尾——这正是 e2e 智能体开路、定位器验证 的设计哲学。相关模块路径定位器入门docs/locators.mdxscreen 与 Locator 完整参考docs/reference/screen.mdx智能体参考docs/reference/agent.mdx定位器核心实现packages/e2e/src/locator/Web 引擎与 test id 配置packages/web/src/engine.ts完整示例项目Vite / Next.js / Expo / SwiftUIexamples/【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考