Playwright文本定位器详解：getByText、getByLabel、getByPlaceholder用法与场景

文本类定位

本教程共 59 篇 · 第 12 篇 · 更新于 2026-08-04 · 约 8 分钟阅读

getByTextgetByLabelgetByPlaceholdergetByAltTextgetByTitle文本定位

本节目标：分清 getByText、getByLabel、getByPlaceholder 各自该在什么场景用，知道文字匹配的规则，并了解 getByAltText 和 getByTitle 这两个近亲。

按文字内容：getByText

getByText() 按元素包含的文字找。适合定位非交互的展示型元素，比如 div、span、p、li。

await expect(page.getByText('Welcome, John')).toBeVisible();

匹配方式有三种：

// 子串匹配，大小写不敏感（默认）
const bySubstring = page.getByText('Welcome');

// 精确匹配，区分大小写
const byExact = page.getByText('Welcome, John', { exact: true });

// 正则匹配
const byRegex = page.getByText(/welcome, [A-Za-z]+$/i);

Note

文字匹配永远先规整空白：多空格并一、换行变空格、去首尾空白。即便 exact: true 也会做这层处理。

Warning

交互元素（按钮、链接、输入框）别用 getByText，改用 getByRole。文字定位适合读出来给人看的内容，不适合「要点要填」的控件。

文字也常用来在列表里挑某项：

await page.getByText('orange').click();

按表单标签：getByLabel

表单控件大多带标签。用 getByLabel() 按标签文字直接定位到那个输入框，最自然。

await page.getByLabel('Password').fill('secret');

对应 DOM 大致是：

<label>Password <input type="password" /></label>

经验法则：定位表单字段，用 getByLabel。它比 CSS 稳，也比按 placeholder 更可靠（标签通常更固定）。

Tip

一个隐藏技巧：Playwright 的填值类操作会自动「认标签、打控件」。你即使对 <label> 调 fill，它实际填的是关联的输入框。但断言文字时打的是标签本身，这点要分清。

按占位符：getByPlaceholder

有些输入框没标签，只有占位提示文字（placeholder）。用 getByPlaceholder() 定位。

await page
  .getByPlaceholder('name@example.com')
  .fill('playwright@microsoft.com');

对应 DOM：

<input type="email" placeholder="name@example.com" />

适用场景：没有 label、只有 placeholder 的表单元素。如果既有 label 又有 placeholder，优先 label。

两个近亲：getByAltText 与 getByTitle

还有两个按「文字属性」定位的，归在同一类：

// 按图片 alt 文本找
await page.getByAltText('playwright logo').click();

// 按 title 属性找
await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

getByAltText：用于 img、area 这类有 alt 的元素。
getByTitle：用于带 title 属性的元素。

小结

文本类定位按场景挑：展示文字用 getByText（子串、精确、正则三种匹配），表单字段用 getByLabel，只有占位符的输入框用 getByPlaceholder，图片用 getByAltText，带 title 的用 getByTitle。

一条主线记住就够：交互控件优先 role，纯文字内容用 text，表单优先 label。实际写测试时，优先挑 getByLabel 和 getByRole，把 getByText 留给纯装饰性文字——这样用例最稳，UI 一改也不容易挂。反过来，按钮、链接这类可交互的，就别按文字去点了。

下一章讲 getByTestId——用 data-testid 做最不受 UI 变动影响的定位，以及怎么自定义这个属性名。