Playwright Locator 类 API
Locator 是 Playwright 的定位器对象，提供链式筛选、操作和断言。
Locator 操作方法
| 方法 | 说明 |
|---|---|
locator.click(options?) | 点击元素 |
locator.dblclick(options?) | 双击元素 |
locator.hover(options?) | 鼠标悬停 |
locator.fill(value, options?) | 清空并填入文本 |
locator.type(text, options?) | 逐字符输入 |
locator.clear(options?) | 清空输入框 |
locator.check(options?) | 勾选复选框 |
locator.uncheck(options?) | 取消勾选 |
locator.setChecked(checked, options?) | 设置复选框状态 |
locator.selectOption(values, options?) | 选择下拉框选项 |
locator.setInputFiles(files, options?) | 设置文件上传 |
locator.dragTo(target, options?) | 拖拽到目标元素 |
locator.press(key, options?) | 按键 |
locator.screenshot(options?) | 元素截图 |
locator.scrollIntoViewIfNeeded(options?) | 滚动到可见 |
Locator 链式筛选
| 方法 | 说明 |
|---|---|
locator.first() | 取第一个匹配元素 |
locator.last() | 取最后一个匹配元素 |
locator.nth(index) | 取第 n 个（从 0 开始） |
locator.filter(options?) | 按条件过滤（hasText、has、hasNot） |
locator.locator(selector) | 在匹配结果中继续查找 |
locator.getByRole(role, options?) | 在匹配结果中按角色查找 |
locator.getByText(text) | 在匹配结果中按文本查找 |
locator.getByLabel(text) | 在匹配结果中按标签查找 |
locator.and(locator) | 逻辑与（1.63+） |
locator.or(locator) | 逻辑或（1.63+） |
Locator 信息获取
| 方法 | 说明 |
|---|---|
locator.textContent(options?) | 获取文本内容 |
locator.innerHTML(options?) | 获取 innerHTML |
locator.innerText(options?) | 获取可见文本 |
locator.inputValue(options?) | 获取 input 值 |
locator.getAttribute(name) | 获取属性值 |
locator.count() | 获取匹配数量 |
locator.isVisible(options?) | 是否可见 |
locator.isHidden(options?) | 是否隐藏 |
locator.isEnabled(options?) | 是否启用 |
locator.isDisabled(options?) | 是否禁用 |
locator.isEditable(options?) | 是否可编辑 |
locator.isChecked(options?) | 是否已勾选 |
locator.boundingBox(options?) | 获取元素位置和大小 |
Locator JS 执行
| 方法 | 说明 |
|---|---|
locator.evaluate(fn, arg?, options?) | 在元素上下文执行 JS |
locator.evaluateAll(fn, arg?) | 在所有匹配元素上执行 JS |
locator.evaluateHandle(fn, arg?, options?) | 执行 JS 并返回 JSHandle |
LocatorAssertions（自动重试）
| 断言方法 | 说明 |
|---|---|
expect(locator).toBeAttached() | 元素在 DOM 中 |
expect(locator).toBeChecked() | 已勾选 |
expect(locator).toBeDisabled() | 已禁用 |
expect(locator).toBeEditable() | 可编辑 |
expect(locator).toBeEmpty() | 内容为空 |
expect(locator).toBeEnabled() | 已启用 |
expect(locator).toBeFocused() | 已获得焦点 |
expect(locator).toBeHidden() | 元素不可见 |
expect(locator).toBeInViewport() | 元素在视口内 |
expect(locator).toBeVisible() | 元素可见 |
expect(locator).toContainText(text) | 包含文本 |
expect(locator).toHaveAccessibleDescription(desc) | 有无障碍描述 |
expect(locator).toHaveAccessibleName(name) | 有无障碍名称 |
expect(locator).toHaveAttribute(name, value?) | 有 DOM 属性 |
expect(locator).toHaveClass(className) | 有 CSS 类名 |
expect(locator).toHaveCount(count) | 有指定数量 |
expect(locator).toHaveCSS(name, value) | 有 CSS 属性值 |
expect(locator).toHaveId(id) | 有 ID |
expect(locator).toHaveText(text) | 文本内容匹配 |
expect(locator).toHaveValue(value) | 输入值匹配 |
expect(locator).toHaveValues(values) | 多值匹配（多选） |
expect(locator).toHaveScreenshot(options?) | 元素截图对比 |
FrameLocator 类
| 方法 | 说明 |
|---|---|
frameLocator.getByRole(role, options?) | 按角色定位 |
frameLocator.getByText(text) | 按文本定位 |
frameLocator.getByLabel(text) | 按标签定位 |
frameLocator.getByPlaceholder(text) | 按占位符定位 |
frameLocator.getByTestId(id) | 按 testId 定位 |
frameLocator.locator(selector) | CSS/XPath 定位 |
frameLocator.frameLocator(selector) | 嵌套 iframe 定位 |
frameLocator.first() | 取第一个 |
frameLocator.last() | 取最后一个 |
frameLocator.nth(index) | 取第 n 个 |
AI 思考中...