跳到主要内容

操作

简介​

Playwright 可以与 HTML 输入元素进行交互，例如文本输入框、复选框、单选按钮、选择选项、鼠标点击、输入字符、按键和快捷键，以及上传文件和聚焦元素。

文本输入​

使用 Locator.fill() 是填充表单字段最简单的方法。它会聚焦元素并触发带有输入文本的 input 事件。它适用于 <input>、<textarea> 和 [contenteditable] 元素。

// 文本输入
page.getByRole(AriaRole.TEXTBOX).fill("Peter");

// 日期输入
page.getByLabel("出生日期").fill("2020-02-02");

// 时间输入
page.getByLabel("预约时间").fill("13-15");

// 本地日期时间输入
page.getByLabel("本地时间").fill("2020-03-02T05:15");

复选框和单选按钮​

使用 Locator.setChecked() 是选中和取消选中复选框或单选按钮最简单的方法。此方法可用于 input[type=checkbox]、input[type=radio] 和 [role=checkbox] 元素。

// 选中复选框
page.getByLabel("我同意上述条款").check();

// 断言选中状态
assertTrue(page.getByLabel("订阅时事通讯").isChecked());

// 选择单选按钮
page.getByLabel("XL").check();

选择选项​

使用 Locator.selectOption() 在 <select> 元素中选择一个或多个选项。你可以指定选项的 value 或 label 来进行选择。可以选择多个选项。

// 匹配值或标签的单选
page.getByLabel("选择一种颜色").selectOption("blue");

// 匹配标签的单选
page.getByLabel("选择一种颜色").selectOption(new SelectOption().setLabel("Blue"));

// 选择多个项目
page.getByLabel("选择多种颜色").selectOption(new String[] {"red", "green", "blue"});

鼠标点击​

执行简单的模拟人类点击操作。

// 普通点击
page.getByRole(AriaRole.BUTTON).click();

// 双击
page.getByText("Item").dblclick();

// 右键点击
page.getByText("Item").click(new Locator.ClickOptions().setButton(MouseButton.RIGHT));

// Shift + 点击
page.getByText("Item").click(new Locator.ClickOptions().setModifiers(Arrays.asList(KeyboardModifier.SHIFT)));

// 在 Windows 和 Linux 上是 Ctrl + 点击
// 在 macOS 上是 Meta + 点击
page.getByText("Item").click(new Locator.ClickOptions().setModifiers(Arrays.asList(KeyboardModifier.CONTROL_OR_META)));

// 悬停在元素上
page.getByText("Item").hover();

// 点击左上角
page.getByText("Item").click(new Locator.ClickOptions().setPosition(0, 0));

在底层，此方法及其他与指针相关的方法会：

  • 等待具有给定选择器的元素出现在 DOM 中
  • 等待元素显示出来，即不为空，没有 display:none，没有 visibility:hidden
  • 等待元素停止移动，例如，直到 CSS 过渡完成
  • 将元素滚动到可见区域
  • 等待元素在操作点接收指针事件，例如，等待元素不再被其他元素遮挡
  • 如果在上述任何检查过程中元素被分离，则重试

强制点击​

有时，应用程序会使用复杂的逻辑，当鼠标悬停在元素上时，会用另一个元素覆盖它，从而拦截点击。这种行为与元素被覆盖且点击被分派到其他地方的错误难以区分。如果你知道发生了这种情况，可以绕过 可操作性 检查并强制点击：

page.getByRole(AriaRole.BUTTON).click(new Locator.ClickOptions().setForce(true));

编程式点击​

如果您不关心在真实条件下测试应用程序，而是希望通过任何可能的方式模拟点击操作，您可以通过 Locator.dispatchEvent() 在元素上简单地派发点击事件，来触发 HTMLElement.click() 行为：

page.getByRole(AriaRole.BUTTON).dispatchEvent("click");

输入字符​

警告

大多数情况下，您应该使用 Locator.fill() 输入文本。请参阅上面的 文本输入 部分。只有在页面上存在特殊键盘处理时，您才需要输入字符。

使用 Locator.pressSequentially() 逐个字符地在输入框中输入内容，就像用户使用真实键盘一样。

// 逐个按键
page.locator("#area").pressSequentially("Hello World!");

此方法将发出所有必要的键盘事件，包括 keydown、keyup、keypress 等事件。您甚至可以指定按键之间的可选 delay，以模拟真实用户行为。

按键和快捷键​

// 按下回车键
page.getByText("Submit").press("Enter");

// 发送 Control+向右箭头
page.getByRole(AriaRole.TEXTBOX).press("Control+ArrowRight");

// 按下键盘上的 $ 符号
page.getByRole(AriaRole.TEXTBOX).press("$");

Locator.press() 方法会聚焦选定的元素并生成单个按键操作。它接受在键盘事件的 keyboardEvent.key 属性中发出的逻辑键名：

Backquote、Minus、Equal、Backslash、Backspace、Tab、Delete、Escape、
ArrowDown、End、Enter、Home、Insert、PageDown、PageUp、ArrowRight、
ArrowUp、F1 - F12、Digit0 - Digit9、KeyA - KeyZ 等。
  • 你也可以指定想要生成的单个字符，例如 "a" 或 "#"。
  • 以下修饰快捷键也受支持：Shift、Control、Alt、Meta。

简单版本会生成单个字符。此字符区分大小写，因此 "a" 和 "A" 将产生不同的结果。

// <input id=name>
page.locator("#name").press("Shift+A");

// <input id=name>
page.locator("#name").press("Shift+ArrowLeft");

诸如 "Control+o" 或 "Control+Shift+T" 之类的快捷键也受支持。当与修饰键一起指定时，在按下后续键时，修饰键会被按下并保持按住状态。

请注意，在 Shift-A 中你仍然需要指定大写的 A 才能生成大写字符。Shift-a 会生成小写字符，就像你切换了 CapsLock 一样。

上传文件​

你可以使用 Locator.setInputFiles() 方法选择要上传的输入文件。它期望第一个参数指向一个类型为 "file" 的 输入元素。可以在数组中传入多个文件。如果某些文件路径是相对路径，则会相对于当前工作目录进行解析。空数组会清除选定的文件。

// 选择单个文件
page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

// 选择多个文件
page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

// 选择一个目录
page.getByLabel("Upload directory").setInputFiles(Paths.get("mydir"));

// 移除所有选定的文件
page.getByLabel("Upload file").setInputFiles(new Path[0]);

// 从内存中上传缓冲区
page.getByLabel("Upload file").setInputFiles(new FilePayload(
  "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

如果你手头没有输入元素（它是动态创建的），你可以处理 Page.onFileChooser(handler) 事件，或者在执行操作时使用相应的等待方法：

FileChooser fileChooser = page.waitForFileChooser(() -> {
  page.getByLabel("Upload file").click();
});
fileChooser.setFiles(Paths.get("myfile.pdf"));

聚焦元素​

对于处理聚焦事件的动态页面，你可以使用 Locator.focus() 聚焦给定元素。

page.getByLabel("Password").focus();

拖放操作​

你可以使用 Locator.dragTo() 执行拖放操作。此方法将：

  • 悬停在要拖动的元素上。
  • 按下鼠标左键。
  • 将鼠标移动到要接收放置的元素上。
  • 释放鼠标左键。
page.locator("#item-to-be-dragged").dragTo(page.locator("#item-to-drop-at"));

手动拖动​

如果你想精确控制拖动操作，可以使用更底层的方法，如 Locator.hover()、Mouse.down()、Mouse.move() 和 Mouse.up()。

page.locator("#item-to-be-dragged").hover();
page.mouse().down();
page.locator("#item-to-drop-at").hover();
page.mouse().up();
备注

如果你的页面依赖于 dragover 事件的触发，那么在所有浏览器中至少需要两次鼠标移动才能触发该事件。为了可靠地执行第二次鼠标移动，重复执行 Mouse.move() 或 Locator.hover() 两次。操作顺序应为：悬停在拖动元素上，按下鼠标，悬停在放置元素上，再次悬停在放置元素上，释放鼠标。

滚动​

大多数情况下，Playwright 会在执行任何操作之前自动为你滚动页面。因此，你无需显式滚动。

// 自动滚动，使按钮可见
page.getByRole(AriaRole.BUTTON).click();

然而，在极少数情况下，你可能需要手动滚动。例如，你可能希望强制“无限列表”加载更多元素，或者为特定截图调整页面位置。在这种情况下，最可靠的方法是找到你希望在底部可见的元素，并将其滚动到视图中。

// 将页脚滚动到视图中，强制“无限列表”加载更多内容
page.getByText("Footer text").scrollIntoViewIfNeeded();

如果你想更精确地控制滚动，可以使用 Mouse.wheel() 或 Locator.evaluate()：

// 定位鼠标并使用鼠标滚轮滚动
page.getByTestId("scrolling-container").hover();
page.mouse.wheel(0, 10);

// 或者，以编程方式滚动特定元素
page.getByTestId("scrolling-container").evaluate("e => e.scrollTop += 100");