自动化测试 / 系统课时

使用角色定位器

使用角色定位器

角色定位器从用户和辅助技术看到的语义出发定位元素,而不是绑定脆弱的 CSS 层级。本节用 getByRole() 同时限定角色与可访问名称,完成输入、点击和结果验证。

学习目标

  • 根据按钮、链接、输入框等可访问角色创建 Locator
  • 使用 name 通过可访问名称缩小匹配范围
  • 识别重复名称、错误角色和结构耦合带来的定位风险

角色和名称共同决定目标

page.getByRole(role, { name }) 按 ARIA 角色与可访问名称匹配元素。很多原生 HTML 元素自带隐式角色,例如 <button> 是 button,带 href 的 <a> 是 link,普通文本输入框通常是 textbox。

可访问名称通常来自按钮可见文字、关联的 <label>、aria-label 等语义来源。因此,与 .toolbar > div:nth-child(2) button 这类结构选择器相比,角色定位器更贴近“用户要操作哪个控件”。

页面元素 典型角色 可访问名称示例
<button>登录</button> button 登录
<a href="/help">帮助</a> link 帮助
<label>邮箱 <input></label> textbox 邮箱

用 getByRole 完成一次交互

下面的测试创建一个最小登录表单,通过 textbox 和 button 的角色与名称完成输入、点击,再用 status 角色验证结果。将代码保存为 tests/role-locator.spec.ts,执行 npx playwright test tests/role-locator.spec.ts:

ts
import { test, expect } from '@playwright/test';

test('locate controls by role and name', async ({ page }) => {
  await page.setContent(`
    <label>邮箱 <input id="email"></label>
    <button type="button" onclick="
      document.querySelector('[role=status]').textContent =
        '已提交 ' + document.querySelector('#email').value
    ">登录</button>
    <p role="status"></p>
  `);

  await page.getByRole('textbox', { name: '邮箱' }).fill('user@example.com');
  await page.getByRole('button', { name: '登录' }).click();

  const status = page.getByRole('status');
  await expect(status).toHaveText('已提交 user@example.com');
  console.log(await status.innerText());
});

预期输出:

text
已提交 user@example.com

为什么角色定位更稳定

Locator 在每次执行动作时都会重新解析当前页面中的匹配元素,因此组件重新渲染后,只要语义没有变化,原来的角色定位器仍能找到新的 DOM 节点。Playwright 还会在点击、填写等动作前自动等待元素达到可操作状态,这比手工查询节点再反复轮询更可靠。

角色定位器也能反向暴露可访问性问题。如果页面上的输入框没有关联标签、多个按钮都叫“确定”,测试会难以写出清晰唯一的定位器,这通常说明真实用户也缺少足够的语义线索。

处理匹配不唯一和角色误判

动作型 Locator 通常要求目标唯一。若同一页面有两个名为“保存”的按钮,不要直接用位置序号掩盖歧义;优先先定位对话框、表单或列表项,再在该范围内继续 getByRole(),或者让控件拥有更明确的可访问名称。

还要注意角色不是标签名。getByRole('button') 查找的是无障碍树中的按钮语义,而不是所有看起来像按钮的元素。一个用普通 <div> 模拟的按钮如果没有正确语义,既可能无法被角色定位器找到,也会影响键盘和辅助技术用户。

写角色定位器时,优先回答两个问题:用户认为它是什么控件,以及用户用什么名称识别它。角色和名称都稳定时,测试往往也更稳定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用角色定位器

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通