自动化测试 / 系统课时
使用文本定位器
使用文本定位器
文本定位器适合从用户实际看到的文字出发查找元素。本课用 getByText() 完成普通文本、精确文本和正则匹配,并重点处理“同一短语同时出现在多个元素中”时容易出现的歧义。
学习目标
- 使用
getByText()按可见文本定位页面元素 - 区分子串匹配、精确匹配和正则表达式匹配
- 在文本重复时通过更明确的条件避免定位歧义
文本定位器匹配什么
page.getByText() 根据元素可见文本创建 Locator,适合状态提示、标题、说明文字等非交互内容。传入普通字符串时默认允许子串匹配,因此 getByText('订单已提交') 既可能匹配完整文本“订单已提交”,也可能匹配“订单已提交,请等待审核”。
如果页面上只有一个目标,这种写法简洁直观;如果同一短语在多个元素中重复出现,后续执行点击或断言时就可能因为匹配到多个元素而失败。此时应主动收紧条件,而不是依赖元素出现顺序。
精确匹配与正则匹配
需要完整字符串匹配时,传入 { exact: true }。精确匹配区分大小写并要求整段文本一致,但 Playwright 仍会规范化空白字符,例如折叠连续空格、将换行视为空格,并忽略首尾空白。
需要表达前缀、后缀或大小写规则时,可以直接传入 JavaScript 正则表达式。正则比模糊字符串更明确,也比依赖 DOM 层级的 CSS 选择器更贴近用户看到的内容。
下面的测试同时验证精确文本与后缀匹配。将内容保存为 text-locator.spec.ts:
import { test, expect } from '@playwright/test';
test('根据可见文本定位状态信息', async ({ page }) => {
await page.setContent(`
<main>
<h2>订单已提交</h2>
<p>订单已提交,请等待审核</p>
</main>
`);
// 精确匹配只选择标题,不会命中较长的提示文本。
await expect(
page.getByText('订单已提交', { exact: true })
).toBeVisible();
// 正则用于表达“以请等待审核结尾”的文本规则。
await expect(page.getByText(/请等待审核$/))
.toHaveText('订单已提交,请等待审核');
});在已安装 Playwright Test 的项目目录运行:
npx playwright test text-locator.spec.ts预期输出:
1 passed (<TIME>)实际耗时和终端格式可能不同,但测试应通过且没有 strict mode 的多元素匹配错误。
什么时候要收紧文本条件
如果 getByText('保存') 同时命中按钮、提示语和对话框正文,不要直接使用 .first() 掩盖歧义。更稳妥的做法是先判断目标语义:交互控件通常优先使用角色定位器,例如 getByRole('button', { name: '保存' });纯文本内容再使用 getByText()。
当文本规则本身足够唯一时,可以使用精确匹配或正则表达式。只有确实需要在某个页面区域内查找时,才先定位容器,再在该 Locator 上继续调用 getByText(),让范围和文本条件共同表达目标。
掌握文本定位的关键不是“能找到元素”,而是让定位条件说明为什么这个元素就是目标。优先选择唯一、稳定且具有用户语义的文本,测试在页面结构调整后会更容易保持可读和可靠。