Playwright 元素定位方式全解

七崽爱吃小饼干2026/05/19阅读 0

Playwright 提供强大、灵活、抗干扰的元素定位能力，支持CSS、XPath、文本、角色、标签属性、伪类等多种定位方式，优先推荐用内置定位器（Locator），稳定性远高于原生选择器。

一、官方推荐

这些是 Playwright 专属定位器，自动等待、自动重试、抗页面变化，生产环境优先用。

1. 角色定位（最符合用户视角，推荐）

按 HTML 语义化角色定位，适配无障碍，最稳定

role匹配元素类型以及role属性
name 属性匹配顺序: aria-label → 文本 → alt → placeholder

// 定位按钮
page.getByRole('button', { name: '登录' })
// 定位输入框
page.getByRole('textbox', { name: '用户名' })
// 定位下拉框、复选框、链接等
page.getByRole('combobox')
page.getByRole('checkbox')
page.getByRole('link', { name: '首页' })

2. 标签属性定位

占位符：输入框 placeholder
js
```
page.getByPlaceholder('请输入手机号')
```
标签文本：label 关联的表单元素
js
```
page.getByLabel('密码')
```
测试 ID（专用定位属性，最推荐团队使用）
html
```
<button data-testid="submit-btn">提交</button>
```
js
```
page.getByTestId('submit-btn')
```
标题：img、svg 的 title
js
```
page.getByTitle('关闭弹窗')
```

3. 文本定位（精准匹配/模糊匹配）

支持完全匹配、包含、正则，自动忽略大小写和空格

// 完全匹配文本
page.getByText('登录成功', { exact: true })
// 包含文本（默认）
page.getByText('欢迎')
// 正则匹配
page.getByText(/^订单\d+$/);

二、通用选择器【兼容传统定位】

和 Selenium 一致，适合熟悉 CSS/XPath 的用户

1. CSS 选择器（最常用）

支持所有标准 CSS 语法 + Playwright 扩展

// 基础选择器
page.locator('#id')
page.locator('.class')
page.locator('div')
page.locator('[name="username"]')

// 组合选择器
page.locator('form input[type="password"]')

// Playwright 扩展：包含文本
page.locator('button:has-text("提交")')
// Playwright 扩展：父元素包含子元素
page.locator('div:has(.error)')

2. XPath 定位

支持绝对/相对路径，适合复杂层级

// 相对路径（推荐）
page.locator('//button[text()="登录"]')
// 包含文本
page.locator('//div[contains(text(),"提示")]')
// 层级定位
page.locator('//form//input[@placeholder="账号"]')

三、高级定位【精准筛选】

1. 过滤定位（filter）

在已有元素基础上二次筛选，非常实用

// 定位所有按钮，再过滤出文本包含“确认”的
page.getByRole('button').filter({ hasText: '确认' })

// 筛选包含子元素的父元素
page.locator('div').filter({ has: page.locator('.icon') })

2. 层级/关系定位

// 子元素
page.locator('ul > li')
// 相邻兄弟元素
page.locator('label + input')
// 父元素下的第 n 个元素
page.locator('tr:nth-child(2)')

3. 伪类定位（Playwright 扩展）

// 可见元素
page.locator(':visible')
// 禁用元素
page.locator(':disabled')
// 选中的单选/复选框
page.locator(':checked')

四、定位优先级（官方建议）

从高到低，越靠前越稳定：

getByTestId（测试 ID，最稳定）
getByRole（语义角色）
getByText / getByLabel / getByPlaceholder
CSS 选择器（id/class/属性）
XPath（最后选择）

五、快速示例（常用组合）

// 1. 测试ID定位（首选）
await page.getByTestId('login-btn').click();

// 2. 角色+文本
await page.getByRole('button', { name: '登录' }).click();

// 3. 输入框占位符
await page.getByPlaceholder('请输入密码').fill('123456');

// 4. CSS 属性选择器
await page.locator('[data-action="save"]').click();

// 5. 文本包含
await page.getByText('提交成功').waitFor();

总结

日常自动化优先用：getByTestId / getByRole，稳定性最强
简单场景：文本、占位符、标签定位
复杂场景：CSS + 过滤（filter）
不推荐：绝对 XPath、易变的 class 名称