# 选择定位策略

> **何时使用**: 当需要决定对某个元素使用哪种 Playwright 定位方法时

## 快速回答

对所有具有语义 HTML 角色（按钮、链接、标题、表单字段、对话框）的元素使用 `getByRole()`。对于表单字段回退到 `getByLabel()`，对于纯文本内容使用 `getByText()`，而 `getByTestId()` 仅作为最后手段，用于没有无障碍角色的自定义组件。

## 决策流程图

```
开始：你需要定位一个元素
  |
  v
该元素是否有语义角色？
（button、link、heading、textbox、checkbox、combobox、dialog、img、row、cell、navigation……）
  |
  +-- 是 --> 使用 getByRole('role', { name: '无障碍名称' })
  |             |
  |             +-- 需要缩小范围？从父级角色定位器开始链式调用：
  |                   getByRole('navigation').getByRole('link', { name: '...' })
  |
  +-- 否
       |
       v
     它是否是一个带有可见 <label> 的表单字段？
       |
       +-- 是 --> 使用 getByLabel('标签文本')
       |
       +-- 否
            |
            v
         它是否是静态文本内容（段落、span、带文本的 div）？
            |
            +-- 是 --> 使用 getByText('文本内容')
            |             当文本较短或常见时，优先使用 { exact: true }
            |
            +-- 否
                 |
                 v
              它是否有占位符（placeholder）？
                 |
                 +-- 是 --> 使用 getByPlaceholder('占位符文本')
                 |             （不太推荐——占位符在输入时消失）
                 |
                 +-- 否
                      |
                      v
                   它是否有 title 属性或 alt 文本？
                      |
                      +-- 是 --> 使用 getByTitle('...') 或 getByAltText('...')
                      |
                      +-- 否
                           |
                           v
                         在标记中添加 data-testid="..."
                         使用 getByTestId('标识符')
                         |
                         +--> 绝不回退到 CSS 选择器或 XPath。
                              应修复标记（markup）而非使用它们。
```

## 决策矩阵

| 元素类型          | 推荐的定位器                                                  | 回退方案                            | 示例                                                                |
| ----------------- | ------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------ |
| 按钮（Button）            | `getByRole('button', { name })`                              | 角色缺失时使用 `getByText()`      | `getByRole('button', { name: 'Submit' })`                          |
| 链接（Link）              | `getByRole('link', { name })`                                | 锚点文本使用 `getByText()`        | `getByRole('link', { name: 'Sign up' })`                            |
| 文本输入（Text input）        | `getByLabel('...')`                                          | `getByRole('textbox', { name })`  | `getByLabel('Email address')`                                      |
| 复选框（Checkbox）          | `getByRole('checkbox', { name })`                            | `getByLabel()`                    | `getByRole('checkbox', { name: 'Accept terms' })`                  |
| 单选按钮（Radio button）      | `getByRole('radio', { name })`                               | `getByLabel()`                    | `getByRole('radio', { name: 'Express shipping' })`                  |
| 下拉框 / 选择框（Dropdown / Select） | `getByRole('combobox', { name })`                            | `getByLabel()`                    | `getByLabel('Country')`                                            |
| 标题（Heading）           | `getByRole('heading', { name, level })`                      | `getByText()`                     | `getByRole('heading', { name: 'Dashboard', level: 1 })`            |
| 导航链接（Nav link）          | 链式调用：`getByRole('navigation').getByRole('link', { name })` | 使用 `locator('nav')` 限定范围    | 见下方详细示例                                                     |
| 表格单元格（Table cell）        | 链式调用：`getByRole('row').filter().getByRole('cell')`         | 限定范围的 `locator('td')`        | 见下方详细示例                                                     |
| 图片（Image）             | `getByRole('img', { name })`                                 | `getByAltText()`                  | `getByRole('img', { name: 'Company logo' })`                       |
| 模态框 / 对话框（Modal / Dialog）    | `getByRole('dialog')` 然后在其中链式调用                        | `locator('[role="dialog"]')`      | `getByRole('dialog').getByRole('button', { name: 'Confirm' })`     |
| 动态列表项（Dynamic list item） | `.filter({ hasText })` 或 `.filter({ has })`                 | 最后手段使用 `nth()`              | `getByRole('listitem').filter({ hasText: 'Milk' })`                |
| 自定义组件（Custom component）  | `getByTestId('...')`                                         | 在标记中添加 `data-testid`        | `getByTestId('color-picker')`                                      |

## 详细分析

### 第一级：`getByRole()` —— 默认使用

最强的定位器。它模拟了辅助技术和真实用户感知页面的方式。

**优点**

- 对标记重构具有弹性（类名、标签变更）
- 强制使用无障碍标记——如果定位器失效，说明你的无障碍也失效了
- 跨框架工作（React、Vue、Angular、纯 HTML）
- 支持按 `name`、`level`、`checked`、`pressed`、`expanded`、`selected` 进行筛选

**缺点**

- 要求元素具有有效的 ARIA 角色（隐式或显式）
- 当名称重复时可能匹配多个元素——使用链式调用限定范围

**何时失效**：使用 `<div>` 堆砌且无 ARIA 角色的自定义组件。先修复组件；只有在无法修改标记时才添加 `getByTestId()`。

---

### 第二级：`getByLabel()` —— 表单字段

通过关联的 `<label>` 文本进行查询。这通常是表单字段最可读的定位器。

**优点**

- 极其可读：`getByLabel('Password')` 明确告诉你是什么字段
- 适用于 `<label for="...">`、包裹式 `<label>` 以及 `aria-labelledby`

**缺点**

- 仅适用于带标签的表单元素
- 如果有人更改标签文本则会失效（但这通常是故意的）

**何时优先于 `getByRole('textbox')`**：当标签文本清晰且唯一时。当你需要按角色类型区分多个相似标签的字段时，使用 `getByRole()`。

---

### 第三级：`getByText()` —— 静态内容

通过可见文本内容查找元素。

**优点**

- 对非交互式文本（段落、span、徽章、状态消息）直观易用
- 支持精确匹配和子串匹配

**缺点**

- 如果文本是动态的、被翻译或重复的，则很脆弱
- 可能无意中匹配到父元素——使用 `{ exact: true }` 或限定查询范围

**经验法则**：将 `getByText()` 用于断言和内容验证，而非交互式元素。交互式元素应使用 `getByRole()`。

---

### 第四级：`getByPlaceholder()` —— 无标签的输入框

通过占位符（placeholder）属性值定位。

**优点**

- 在缺少标签时可用（搜索栏、极简 UI）

**缺点**

- 占位符在用户输入时消失——用户体验基础较差
- 表明无障碍性缺失（没有标签）

**将其视为黄旗警示**：如果你使用了此方法，请考虑提交工单以添加合适的标签。

---

### 第五级：`getByTestId()` —— 最后手段

通过 `data-testid` 属性定位。

**优点**

- 完全与面向用户的文本和结构解耦
- 在 UI 重新设计时保持稳定

**缺点**

- 对用户和辅助技术不可见
- 污染生产环境的标记（除非在构建时剥离）
- 无法说明该元素的外观或功能

**仅在以下情况使用**：组件没有语义角色、没有标签、没有文本，并且你无法修改标记。常见情况：canvas 元素、第三方小部件、复杂的自定义组件。

---

### 绝不使用：原生 CSS 选择器或 XPath

```
// 不要这样做
page.locator('.btn-primary');           // 类名会变
page.locator('#submit-btn');            // ID 很脆弱
page.locator('div > span:nth-child(2)'); // 结构变化会破坏它
page.locator('xpath=//div[@class="foo"]'); // 不可读，很脆弱
```

如果你正要使用 CSS 选择器，请停下来。回到决策流程图，找一个语义定位器。如果找不到，则添加 `data-testid`。

## 实际示例

### 1. 按钮

```typescript
// TypeScript
// 标准按钮
await page.getByRole("button", { name: "Submit" }).click()

// 纯图标按钮（使用 aria-label）
await page.getByRole("button", { name: "Close" }).click()

// 特定区域内的按钮
await page.getByRole("region", { name: "Billing" }).getByRole("button", { name: "Update" }).click()
```

```javascript
// JavaScript
// 标准按钮
await page.getByRole("button", { name: "Submit" }).click()

// 纯图标按钮（使用 aria-label）
await page.getByRole("button", { name: "Close" }).click()

// 特定区域内的按钮
await page.getByRole("region", { name: "Billing" }).getByRole("button", { name: "Update" }).click()
```

---

### 2. 链接

```typescript
// TypeScript
// 标准链接
await page.getByRole("link", { name: "Sign up" }).click()

// 导航内的链接
await page.getByRole("navigation").getByRole("link", { name: "Pricing" }).click()

// 精确匹配链接（避免部分匹配）
await page.getByRole("link", { name: "Log in", exact: true }).click()
```

```javascript
// JavaScript
await page.getByRole("link", { name: "Sign up" }).click()

await page.getByRole("navigation").getByRole("link", { name: "Pricing" }).click()

await page.getByRole("link", { name: "Log in", exact: true }).click()
```

---

### 3. 文本输入框

```typescript
// TypeScript
// 带有可见标签的输入框——推荐
await page.getByLabel("Email address").fill("user@example.com")

// 当存在多个文本框且需要按角色区分时
await page.getByRole("textbox", { name: "Email address" }).fill("user@example.com")

// 文本域（Textarea）
await page.getByLabel("Message").fill("Hello, world")

// 搜索输入框（角色为 searchbox）
await page.getByRole("searchbox", { name: "Search" }).fill("playwright")
```

```javascript
// JavaScript
await page.getByLabel("Email address").fill("user@example.com")

await page.getByRole("textbox", { name: "Email address" }).fill("user@example.com")

await page.getByLabel("Message").fill("Hello, world")

await page.getByRole("searchbox", { name: "Search" }).fill("playwright")
```

---

### 4. 复选框与单选按钮

```typescript
// TypeScript
// 复选框
await page.getByRole("checkbox", { name: "Accept terms" }).check()

// 验证选中状态
await expect(page.getByRole("checkbox", { name: "Accept terms" })).toBeChecked()

// 单选按钮
await page.getByRole("radio", { name: "Express shipping" }).check()

// 组内的单选按钮（使用 fieldset + legend）
await page
  .getByRole("group", { name: "Shipping method" })
  .getByRole("radio", { name: "Express" })
  .check()
```

```javascript
// JavaScript
await page.getByRole("checkbox", { name: "Accept terms" }).check()

await expect(page.getByRole("checkbox", { name: "Accept terms" })).toBeChecked()

await page.getByRole("radio", { name: "Express shipping" }).check()

await page
  .getByRole("group", { name: "Shipping method" })
  .getByRole("radio", { name: "Express" })
  .check()
```

---

### 5. 下拉框与选择框

```typescript
// TypeScript
// 原生 <select> 元素
await page.getByLabel("Country").selectOption("Canada")

// 自定义组合框（ARIA combobox 角色）
await page.getByRole("combobox", { name: "Country" }).click()
await page.getByRole("option", { name: "Canada" }).click()

// Listbox 模式
await page.getByRole("combobox", { name: "Font size" }).click()
await page.getByRole("listbox").getByRole("option", { name: "16px" }).click()
```

```javascript
// JavaScript
await page.getByLabel("Country").selectOption("Canada")

await page.getByRole("combobox", { name: "Country" }).click()
await page.getByRole("option", { name: "Canada" }).click()

await page.getByRole("combobox", { name: "Font size" }).click()
await page.getByRole("listbox").getByRole("option", { name: "16px" }).click()
```

---

### 6. 标题

```typescript
// TypeScript
// 指定标题级别
await expect(page.getByRole("heading", { name: "Dashboard", level: 1 })).toBeVisible()

// 仅按名称匹配任意标题（级别不重要时）
await expect(page.getByRole("heading", { name: "Recent activity" })).toBeVisible()

// 某区域内的标题
await page.getByRole("region", { name: "Sidebar" }).getByRole("heading", { name: "Categories" })
```

```javascript
// JavaScript
await expect(page.getByRole("heading", { name: "Dashboard", level: 1 })).toBeVisible()

await expect(page.getByRole("heading", { name: "Recent activity" })).toBeVisible()

await page.getByRole("region", { name: "Sidebar" }).getByRole("heading", { name: "Categories" })
```

---

### 7. 导航项

```typescript
// TypeScript
// 主导航内的链接
await page.getByRole("navigation").getByRole("link", { name: "Pricing" }).click()

// 存在多个导航时，通过 aria-label 缩小范围
await page
  .getByRole("navigation", { name: "Main menu" })
  .getByRole("link", { name: "Pricing" })
  .click()

// 面包屑导航
await page
  .getByRole("navigation", { name: "Breadcrumb" })
  .getByRole("link", { name: "Products" })
  .click()
```

```javascript
// JavaScript
await page.getByRole("navigation").getByRole("link", { name: "Pricing" }).click()

await page
  .getByRole("navigation", { name: "Main menu" })
  .getByRole("link", { name: "Pricing" })
  .click()

await page
  .getByRole("navigation", { name: "Breadcrumb" })
  .getByRole("link", { name: "Products" })
  .click()
```

---

### 8. 表格单元格

```typescript
// TypeScript
// 在特定行中查找单元格
await page.getByRole("row", { name: /Jane Smith/ }).getByRole("cell", { name: "$120.00" })

// 点击特定行中的操作按钮
await page
  .getByRole("row", { name: /Jane Smith/ })
  .getByRole("button", { name: "Edit" })
  .click()

// 使用 .filter() 进行复杂匹配来筛选行
const row = page.getByRole("row").filter({ hasText: "Pending" })
await row.getByRole("button", { name: "Approve" }).click()

// 验证表头存在
await expect(page.getByRole("columnheader", { name: "Status" })).toBeVisible()
```

```javascript
// JavaScript
await page.getByRole("row", { name: /Jane Smith/ }).getByRole("cell", { name: "$120.00" })

await page
  .getByRole("row", { name: /Jane Smith/ })
  .getByRole("button", { name: "Edit" })
  .click()

const row = page.getByRole("row").filter({ hasText: "Pending" })
await row.getByRole("button", { name: "Approve" }).click()

await expect(page.getByRole("columnheader", { name: "Status" })).toBeVisible()
```

---

### 9. 图片

```typescript
// TypeScript
// 带有 alt 文本的图片
await expect(page.getByRole("img", { name: "Company logo" })).toBeVisible()

// 备选：getByAltText（结果相同，不太推荐）
await expect(page.getByAltText("Company logo")).toBeVisible()

// 卡片内的头像图片
await page
  .locator("article")
  .filter({ hasText: "Jane Smith" })
  .getByRole("img", { name: "Jane Smith's avatar" })
```

```javascript
// JavaScript
await expect(page.getByRole("img", { name: "Company logo" })).toBeVisible()

await expect(page.getByAltText("Company logo")).toBeVisible()

await page
  .locator("article")
  .filter({ hasText: "Jane Smith" })
  .getByRole("img", { name: "Jane Smith's avatar" })
```

---

### 10. 自定义组件（无 ARIA 角色）

```typescript
// TypeScript
// 第三方颜色选择器，无语义角色
await page.getByTestId("color-picker").click()

// 自定义拖放区域
await page.getByTestId("drop-zone").dispatchEvent("drop", { dataTransfer })

// 基于 Canvas 的图表
const chart = page.getByTestId("revenue-chart")
await expect(chart).toBeVisible()
```

```javascript
// JavaScript
await page.getByTestId("color-picker").click()

await page.getByTestId("drop-zone").dispatchEvent("drop", { dataTransfer })

const chart = page.getByTestId("revenue-chart")
await expect(chart).toBeVisible()
```

**在使用 `getByTestId` 之前，先问问自己**：我能否为此组件添加 `role` 和 `aria-label`？如果可以，就这样做并使用 `getByRole()`。

---

### 11. 动态列表

```typescript
// TypeScript
// 按文本筛选列表项
const item = page.getByRole("listitem").filter({ hasText: "Milk" })
await item.getByRole("button", { name: "Remove" }).click()

// 按子级定位器筛选
const card = page.locator(".product-card").filter({
  has: page.getByText("Out of stock"),
})
await expect(card).toHaveCount(3)

// 统计列表项数量
await expect(page.getByRole("listitem")).toHaveCount(5)

// 遍历列表项进行复杂断言
for (const item of await page.getByRole("listitem").all()) {
  await expect(item).toContainText("$")
}
```

```javascript
// JavaScript
const item = page.getByRole("listitem").filter({ hasText: "Milk" })
await item.getByRole("button", { name: "Remove" }).click()

const card = page.locator(".product-card").filter({
  has: page.getByText("Out of stock"),
})
await expect(card).toHaveCount(3)

await expect(page.getByRole("listitem")).toHaveCount(5)

for (const item of await page.getByRole("listitem").all()) {
  await expect(item).toContainText("$")
}
```

---

### 12. 模态框与对话框

```typescript
// TypeScript
// 等待对话框出现，然后在其中进行交互
const dialog = page.getByRole("dialog", { name: "Confirm deletion" })
await expect(dialog).toBeVisible()
await dialog.getByRole("button", { name: "Delete" }).click()

// 在对话框内填写表单
const modal = page.getByRole("dialog", { name: "Edit profile" })
await modal.getByLabel("Display name").fill("Jane")
await modal.getByRole("button", { name: "Save" }).click()

// 验证对话框已关闭
await expect(dialog).toBeHidden()
```

```javascript
// JavaScript
const dialog = page.getByRole("dialog", { name: "Confirm deletion" })
await expect(dialog).toBeVisible()
await dialog.getByRole("button", { name: "Delete" }).click()

const modal = page.getByRole("dialog", { name: "Edit profile" })
await modal.getByLabel("Display name").fill("Jane")
await modal.getByRole("button", { name: "Save" }).click()

await expect(dialog).toBeHidden()
```

## 应避免的反模式

| 反模式                                              | 失败原因                                                  | 应使用的方法                                                    |
| -------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------- |
| `page.locator('.btn-primary')`                     | 类名在重构和重新设计时会改变                               | `getByRole('button', { name: '...' })`                         |
| `page.locator('#email-input')`                     | ID 是实现细节，而非用户可见内容                            | `getByLabel('Email')`                                          |
| `page.locator('div > form > input:first-child')`   | 任何结构变化都会破坏该选择器                               | `getByLabel('...')` 或 `getByRole('textbox', { name: '...' })` |
| `page.locator('[data-testid="submit"]')`           | 对测试 ID 使用原生 CSS——应使用内置方法                     | `getByTestId('submit')`                                        |
| 对按钮使用 `page.getByText('Submit')`              | 匹配任何包含该文本的元素，而非仅限按钮                     | `getByRole('button', { name: 'Submit' })`                      |
| `page.locator('button').nth(2)`                    | 基于索引——顺序改变时就会失效                               | `getByRole('button', { name: '...' })`                         |

## 范围限定策略：当多个元素匹配时

当定位器匹配到多个元素时，应缩小范围而非使用 `nth()`：

```typescript
// 错误：脆弱的索引
page.getByRole("button", { name: "Edit" }).nth(0)

// 正确：范围限定到父级区域
page.getByRole("region", { name: "Billing" }).getByRole("button", { name: "Edit" })

// 正确：范围限定到表格行
page.getByRole("row", { name: /Order #1234/ }).getByRole("button", { name: "Edit" })

// 正确：使用 filter 限定范围
page.locator("article").filter({ hasText: "Draft" }).getByRole("button", { name: "Edit" })
```

## 相关链接

- [Playwright Locators 文档](https://playwright.dev/docs/locators)
- [Playwright 最佳实践](https://playwright.dev/docs/best-practices)
- [ARIA 角色参考（MDN）](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles)