按角色定位 getByRole

为什么首推角色定位

page.getByRole() 依据元素的角色（Role）来找。角色是浏览器和辅助技术（如读屏软件）看待页面的方式：这是个按钮，还是个复选框，还是个标题。

它最贴近「真实用户怎么感知页面」。用户不关心你的 div 嵌套了几层，只在乎「那个提交按钮在哪」。所以用角色定位的用例，页面样式一改也不容易挂。

await page.getByRole('button', { name: 'Sign in' }).click();

第二个参数 { name: 'Sign in' } 是无障碍名称（Accessible Name，读屏软件念出来的那个名字）。加上它，才能从一堆按钮里精确锁定那一个。

常见角色

HTML 元素大多有「隐式角色」。<button> 就是 button，<h1>~<h6> 是 heading，<a> 是 link。常见角色包括：

• button：按钮
• link：链接
• heading：标题（配合 level 指定 h1/h2…）
• checkbox：复选框
• radio：单选
• textbox：文本输入
• listitem：列表项
• dialog：对话框
• navigation：导航区
• table / row / cell：表格相关

完整清单遵循 W3C 的 ARIA 规范。规则是：尽量给角色，再配名称。

// 标题「Sign up」
await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

// 名为 Subscribe 的复选框，打勾
await page.getByRole('checkbox', { name: 'Subscribe' }).check();

// 名为 submit 的按钮，正则不区分大小写
await page.getByRole('button', { name: /submit/i }).click();

可选参数一览

getByRole 第二个对象支持一堆精确化参数：

• name：无障碍名称，可传字符串或正则
• exact：名称是否精确匹配（默认子串、不区分大小写）
• checked：筛选已勾选/未勾选的状态
• disabled：筛选禁用/可用
• selected：筛选已选中状态
• expanded：筛选展开/收起（如折叠面板）
• pressed：筛选按钮的按下态
• level：配合 heading，指定 1~6 级
• includeHidden：是否包含视觉隐藏但语义在的元素（默认不含）
• description：无障碍描述（v1.60 起支持）

几个例子：

// 精确匹配标题文字
await expect(page.getByRole('heading', { name: '设置', exact: true })).toBeVisible();

// 二级标题
const h2 = page.getByRole('heading', { level: 2 });

// 已勾选的复选框
await expect(page.getByRole('checkbox', { checked: true })).toHaveCount(1);

// 已展开的折叠项，点一下收起来
await page.getByRole('button', { expanded: true }).click();

何时用角色定位

经验法则：能用角色定位的，优先用它。尤其这些交互元素：

• 按钮、链接、复选框、单选、输入框 → 用角色
• 标题、对话框、导航 → 用角色
• 非交互的纯展示文字（div、span、p）→ 用 getByText（下一章讲）

小结

getByRole 按 ARIA 角色加无障碍名称定位，最贴近用户和读屏软件看页面的方式，是 Playwright 首推的写法。

常用角色就 button、link、heading、checkbox、textbox 这几个。拿不准就配上 name，还不够再用 checked、level、expanded 这类参数收窄。

下一章看文本类定位：getByText、getByLabel、getByPlaceholder 各自该在什么场景用。