拓冰网站定制 
e2e 屏幕对象screenAPI 参考getByRole 等定位方法完整清单【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2ee2e 是一个面向 Web 与移动应用的下一代端到端测试框架而screen是它所有测试中的核心 fixture通过screen提供的getByRole、getByLabel、getByText、getByTestId等 6 种定位方法你可以在浏览器和手机真机/模拟器上用同一套 API 精确找到页面上的任何控件。本文是一份面向新手的 e2e 屏幕对象screenAPI 参考完整清单式讲解每种定位方法的用法、匹配规则和超时行为帮你快速写出稳定的 e2e 定位代码。一、screen 是什么e2e 定位方法的统一入口每个测试都会自动注入screenfixture。你在测试里写的每一个getBy*查询都返回一个Locator定位器它是惰性的调用时不查页面、不产生开销直到真正执行动作点击、填值或读取文本、属性时才去解析节点。// 语义查询role name 优先label 次之test id 兜底 await screen.getByRole(button, Greet).click(); await screen.getByLabel(Name).fill(Ada);这种Web 一套写法、移动端同样有效的设计是 e2e 屏幕对象的最大特点getByRole(button)在浏览器里找按钮元素在 iOS 设备上同样找到原生按钮因为每个引擎都会把平台的元素类型映射到同一套语义角色。下面这张截图就是一个被测示例应用官方 Vite 示例项目正是用getByRole(heading, Say hello)这类定位来测它的 一个 Locator 的所有getBy*方法还能继续链式调用作用域自动收窄到该节点的子树内例如row.getByRole(button, Archive)。二、getBy 定位方法完整清单6 种查询一览以下是screen上全部 6 种定位方法的完整清单源码定义见 docs/reference/screen.mdx定位方法按什么找典型示例getByRole(role, name?)无障碍角色 名称首选screen.getByRole(button, Sign in)getByLabel(text)表单字段的可访问标签screen.getByLabel(Email)getByPlaceholder(text)输入框占位提示文字screen.getByPlaceholder(Search...)getByText(text)页面上可见的文字screen.getByText(Welcome back)getByDisplayValue(value)控件当前显示的值screen.getByDisplayValue(Pro)getByTestId(id)测试专用 IDWeb 默认data-testidscreen.getByTestId(todo-3)官方推荐的优先级是role name 第一label 第二test id 最后——语义定位最抗改版test id 适合无语义的内部节点。真实用例可以直接看官方示例 examples/with-vite/tests/greeting.e2e.tsawait expect(screen.getByRole(heading, Say hello)).toBeVisible(); await screen.getByRole(button, Greet).click();三、getByRole 详解角色词表与状态过滤getByRole接受一个闭集角色词表约 50 个包括button、link、textbox、searchbox、combobox、checkbox、radio、switch、slider、heading、tab、menuitem、listitem、row、cell、dialog、alert、status等。传一个词表外的角色会直接是类型错误帮你提前发现拼写问题。第二个参数是可访问名称字符串或正则getByRole(button, Save)与对象写法getByRole(button, { name: Save })等价。支持状态过滤{ checked, disabled, selected, expanded, pressed, level }例如getByRole(heading, /welcome/i, { level: 1 })只找一级标题。img是image的别名从 Playwright 迁移过来的getByRole(img, ...)无需改动。角色查询永远不会匹配对辅助功能树隐藏的节点不渲染、或aria-hidden下的内容。四、文本匹配规则字符串、正则与 exact 选项传给getByRolename、getByLabel、getByPlaceholder、getByText、getByDisplayValue的文本有三种匹配方式传入形式匹配行为字符串默认整段精确匹配区分大小写忽略空白差异——Save不会匹配Save changes{ exact: false }不区分大小写的子串匹配RegExp正则按正则本身的 source 和 flags 匹配⚠️ 这是从 Playwright 迁移时最容易踩的坑Playwright 的字符串默认是子串匹配而 e2e 默认是整段匹配。迁移指南 docs/migrate/playwright.mdx 建议原来匹配片段的查询补上{ exact: false }或改正则。五、收窄定位器实战filter、first、nth 与 visible动作类操作要求查询恰好命中一个节点多个匹配会立即报LOCATOR_AMBIGUOUS。收窄工具有四个.filter({ hasText })按节点及其后代的文本过滤不区分大小写的子串匹配.filter({ has })按子树里能否找到某个 Locator过滤。.first()/.last()/.nth(i)取第 n 个匹配0 起。{ visible: true }先剔除平台报告为隐藏的节点再做唯一性判断。框架常把内容保留隐藏副本收起的抽屉、未激活的 tab 面板加visible: true后只有一个可见双胞胎能命中。const row screen.getByRole(listitem).filter({ hasText: Invoice 42 }); await row.getByRole(button, Void).tap();六、screen 级动作tapAt、swipe 与 scrollUntilVisible除了 6 种查询screen还提供 3 个视口级操作专门处理树里没有节点的场景画布、地图、长列表方法作用典型场景tapAt(point)点击视口坐标点不解析节点点击地图上的图钉swipe(options)视口级滑动手势{ direction, momentum }滚动或{ from, to }沿路径拖动左滑删除、拖动卡片换列scrollUntilVisible(target)自动反复滚动直到某 Locator 可见或超时无限列表里找到Accept按钮await screen.scrollUntilVisible(screen.getByRole(button, Accept));scrollUntilVisible用在 Locator 上时滚动的是那个节点自己的滚动容器适合 feed、表格这类独立滚动区域。七、Locator 动作与读取完整清单每个查询返回的 Locator 继承全部screen查询方法并增加两大组方法完整签名见 docs/reference/screen.mdx 的 Locator 部分动作类各自解析唯一节点、等待可操作后执行默认超时 30000ms方法作用方法作用tap()/click()点击click 是别名check()/uncheck()勾选 / 取消勾选doubleTap()双击 / 双指点selectOption(value)下拉框选择选项secondaryTap()右键 / 双指点focus()/hover()聚焦 / 悬停longPress()长按100~10000mssetInputFiles(paths)文件上传fill(value)整体填充输入框dragTo(target)拖拽到目标pressSequentially(text)逐字符键盘输入scrollIntoView()滚动进可视区clear()/press(key)清空 / 发送按键swipe(options)节点级滑动读取类读取当前值、不等待变化textContent()、inputValue()、getAttribute(name)、isVisible()/isHidden()、isEnabled()/isDisabled()、isChecked()、boundingBox()、count()、all()、allTextContents()、waitFor({ state })。八、匹配数量与超时行为速查表这是写稳定 e2e 定位代码最需要记住的一张表操作0 个匹配多个匹配动作tap、fill…轮询直到超时报LOCATOR_NOT_FOUND立即报LOCATOR_AMBIGUOUS读取textContent…立即报LOCATOR_NOT_FOUNDLOCATOR_AMBIGUOUScount()/all()/allTextContents()返回0/[]/[]返回实际数量 / 每个匹配一个 LocatorisVisible()/isHidden()false/trueLOCATOR_AMBIGUOUSexpect断言轮询直到超时默认 5000msLOCATOR_AMBIGUOUS一句话总结动作和断言会自动等待直接读取不会。想让等待生效用expect(locator)或locator.waitFor()断言的完整 matcher 清单见 docs/reference/expect.mdx。九、源码与文档索引想深入 screen 对象的实现可以从以下文件入手 官方参考文档本文主要来源docs/reference/screen.mdx 定位器使用指南查询、动作、断言三合一示例docs/locators.mdx 断言 matcher 参考docs/reference/expect.mdx Screen/Locator 运行时实现packages/e2e/src/locator/screen.ts 定位表达式构建role、text、testId 查询packages/e2e/src/locator/expression.ts 定位引擎桥接属性读取、可见性判断packages/e2e/src/locator/engine.ts 真实 Web 测试用例examples/with-vite/tests/greeting.e2e.ts 移动端测试目标Expo 示例apps/mobile-benchmark/src/Examples/掌握getByRole等 6 种定位方法 4 个收窄工具 这张超时行为表你就拥有了 e2e 屏幕对象 API 的完整地图——从表单登录到无限列表一套语义化 API 同时覆盖 Web 与移动端。【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 e2e 屏幕对象（screen）API 参考：getByRole 等定位方法完整清单
e2e 屏幕对象screenAPI 参考getByRole 等定位方法完整清单【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2ee2e 是一个面向 Web 与移动应用的下一代端到端测试框架而screen是它所有测试中的核心 fixture通过screen提供的getByRole、getByLabel、getByText、getByTestId等 6 种定位方法你可以在浏览器和手机真机/模拟器上用同一套 API 精确找到页面上的任何控件。本文是一份面向新手的 e2e 屏幕对象screenAPI 参考完整清单式讲解每种定位方法的用法、匹配规则和超时行为帮你快速写出稳定的 e2e 定位代码。一、screen 是什么e2e 定位方法的统一入口每个测试都会自动注入screenfixture。你在测试里写的每一个getBy*查询都返回一个Locator定位器它是惰性的调用时不查页面、不产生开销直到真正执行动作点击、填值或读取文本、属性时才去解析节点。// 语义查询role name 优先label 次之test id 兜底 await screen.getByRole(button, Greet).click(); await screen.getByLabel(Name).fill(Ada);这种Web 一套写法、移动端同样有效的设计是 e2e 屏幕对象的最大特点getByRole(button)在浏览器里找按钮元素在 iOS 设备上同样找到原生按钮因为每个引擎都会把平台的元素类型映射到同一套语义角色。下面这张截图就是一个被测示例应用官方 Vite 示例项目正是用getByRole(heading, Say hello)这类定位来测它的 一个 Locator 的所有getBy*方法还能继续链式调用作用域自动收窄到该节点的子树内例如row.getByRole(button, Archive)。二、getBy 定位方法完整清单6 种查询一览以下是screen上全部 6 种定位方法的完整清单源码定义见 docs/reference/screen.mdx定位方法按什么找典型示例getByRole(role, name?)无障碍角色 名称首选screen.getByRole(button, Sign in)getByLabel(text)表单字段的可访问标签screen.getByLabel(Email)getByPlaceholder(text)输入框占位提示文字screen.getByPlaceholder(Search...)getByText(text)页面上可见的文字screen.getByText(Welcome back)getByDisplayValue(value)控件当前显示的值screen.getByDisplayValue(Pro)getByTestId(id)测试专用 IDWeb 默认data-testidscreen.getByTestId(todo-3)官方推荐的优先级是role name 第一label 第二test id 最后——语义定位最抗改版test id 适合无语义的内部节点。真实用例可以直接看官方示例 examples/with-vite/tests/greeting.e2e.tsawait expect(screen.getByRole(heading, Say hello)).toBeVisible(); await screen.getByRole(button, Greet).click();三、getByRole 详解角色词表与状态过滤getByRole接受一个闭集角色词表约 50 个包括button、link、textbox、searchbox、combobox、checkbox、radio、switch、slider、heading、tab、menuitem、listitem、row、cell、dialog、alert、status等。传一个词表外的角色会直接是类型错误帮你提前发现拼写问题。第二个参数是可访问名称字符串或正则getByRole(button, Save)与对象写法getByRole(button, { name: Save })等价。支持状态过滤{ checked, disabled, selected, expanded, pressed, level }例如getByRole(heading, /welcome/i, { level: 1 })只找一级标题。img是image的别名从 Playwright 迁移过来的getByRole(img, ...)无需改动。角色查询永远不会匹配对辅助功能树隐藏的节点不渲染、或aria-hidden下的内容。四、文本匹配规则字符串、正则与 exact 选项传给getByRolename、getByLabel、getByPlaceholder、getByText、getByDisplayValue的文本有三种匹配方式传入形式匹配行为字符串默认整段精确匹配区分大小写忽略空白差异——Save不会匹配Save changes{ exact: false }不区分大小写的子串匹配RegExp正则按正则本身的 source 和 flags 匹配⚠️ 这是从 Playwright 迁移时最容易踩的坑Playwright 的字符串默认是子串匹配而 e2e 默认是整段匹配。迁移指南 docs/migrate/playwright.mdx 建议原来匹配片段的查询补上{ exact: false }或改正则。五、收窄定位器实战filter、first、nth 与 visible动作类操作要求查询恰好命中一个节点多个匹配会立即报LOCATOR_AMBIGUOUS。收窄工具有四个.filter({ hasText })按节点及其后代的文本过滤不区分大小写的子串匹配.filter({ has })按子树里能否找到某个 Locator过滤。.first()/.last()/.nth(i)取第 n 个匹配0 起。{ visible: true }先剔除平台报告为隐藏的节点再做唯一性判断。框架常把内容保留隐藏副本收起的抽屉、未激活的 tab 面板加visible: true后只有一个可见双胞胎能命中。const row screen.getByRole(listitem).filter({ hasText: Invoice 42 }); await row.getByRole(button, Void).tap();六、screen 级动作tapAt、swipe 与 scrollUntilVisible除了 6 种查询screen还提供 3 个视口级操作专门处理树里没有节点的场景画布、地图、长列表方法作用典型场景tapAt(point)点击视口坐标点不解析节点点击地图上的图钉swipe(options)视口级滑动手势{ direction, momentum }滚动或{ from, to }沿路径拖动左滑删除、拖动卡片换列scrollUntilVisible(target)自动反复滚动直到某 Locator 可见或超时无限列表里找到Accept按钮await screen.scrollUntilVisible(screen.getByRole(button, Accept));scrollUntilVisible用在 Locator 上时滚动的是那个节点自己的滚动容器适合 feed、表格这类独立滚动区域。七、Locator 动作与读取完整清单每个查询返回的 Locator 继承全部screen查询方法并增加两大组方法完整签名见 docs/reference/screen.mdx 的 Locator 部分动作类各自解析唯一节点、等待可操作后执行默认超时 30000ms方法作用方法作用tap()/click()点击click 是别名check()/uncheck()勾选 / 取消勾选doubleTap()双击 / 双指点selectOption(value)下拉框选择选项secondaryTap()右键 / 双指点focus()/hover()聚焦 / 悬停longPress()长按100~10000mssetInputFiles(paths)文件上传fill(value)整体填充输入框dragTo(target)拖拽到目标pressSequentially(text)逐字符键盘输入scrollIntoView()滚动进可视区clear()/press(key)清空 / 发送按键swipe(options)节点级滑动读取类读取当前值、不等待变化textContent()、inputValue()、getAttribute(name)、isVisible()/isHidden()、isEnabled()/isDisabled()、isChecked()、boundingBox()、count()、all()、allTextContents()、waitFor({ state })。八、匹配数量与超时行为速查表这是写稳定 e2e 定位代码最需要记住的一张表操作0 个匹配多个匹配动作tap、fill…轮询直到超时报LOCATOR_NOT_FOUND立即报LOCATOR_AMBIGUOUS读取textContent…立即报LOCATOR_NOT_FOUNDLOCATOR_AMBIGUOUScount()/all()/allTextContents()返回0/[]/[]返回实际数量 / 每个匹配一个 LocatorisVisible()/isHidden()false/trueLOCATOR_AMBIGUOUSexpect断言轮询直到超时默认 5000msLOCATOR_AMBIGUOUS一句话总结动作和断言会自动等待直接读取不会。想让等待生效用expect(locator)或locator.waitFor()断言的完整 matcher 清单见 docs/reference/expect.mdx。九、源码与文档索引想深入 screen 对象的实现可以从以下文件入手 官方参考文档本文主要来源docs/reference/screen.mdx 定位器使用指南查询、动作、断言三合一示例docs/locators.mdx 断言 matcher 参考docs/reference/expect.mdx Screen/Locator 运行时实现packages/e2e/src/locator/screen.ts 定位表达式构建role、text、testId 查询packages/e2e/src/locator/expression.ts 定位引擎桥接属性读取、可见性判断packages/e2e/src/locator/engine.ts 真实 Web 测试用例examples/with-vite/tests/greeting.e2e.ts 移动端测试目标Expo 示例apps/mobile-benchmark/src/Examples/掌握getByRole等 6 种定位方法 4 个收窄工具 这张超时行为表你就拥有了 e2e 屏幕对象 API 的完整地图——从表单登录到无限列表一套语义化 API 同时覆盖 Web 与移动端。【免费下载链接】e2eNext generation e2e testing framework for web and mobile apps.项目地址: https://gitcode.com/GitHub_Trending/e2e6/e2e创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考