跳到主要内容

操作

介绍​

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

文本输入​

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

// Text input
page.getByRole(AriaRole.TEXTBOX).fill("Peter");

// Date input
page.getByLabel("Birth date").fill("2020-02-02");

// Time input
page.getByLabel("Appointment time").fill("13-15");

// Local datetime input
page.getByLabel("Local time").fill("2020-03-02T05:15");

复选框和单选按钮​

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

// Check the checkbox
page.getByLabel("I agree to the terms above").check();

// Assert the checked state
assertTrue(page.getByLabel("Subscribe to newsletter")).isChecked();

// Select the radio button
page.getByLabel("XL").check();

选择选项​

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

// Single selection matching the value or label
page.getByLabel("Choose a color").selectOption("blue");

// Single selection matching the label
page.getByLabel("Choose a color").selectOption(new SelectOption().setLabel("Blue"));

// Multiple selected items
page.getByLabel("Choose multiple colors").selectOption(new String[] {"red", "green", "blue"});

鼠标点击​

执行一次简单的模拟用户点击。

// Generic click
page.getByRole(AriaRole.BUTTON).click();

// Double click
page.getByText("Item").dblclick();

// Right click
page.getByText("Item").click(new Locator.ClickOptions().setButton(MouseButton.RIGHT));

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

// Ctrl + click on Windows and Linux
// Meta + click on macOS
page.getByText("Item").click(new Locator.ClickOptions().setModifiers(Arrays.asList(KeyboardModifier.CONTROL_OR_META)));

// Hover over element
page.getByText("Item").hover();

// Click the top left corner
page.getByText("Item").click(new Locator.ClickOptions().setPosition(0, 0));

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

  • 等待具有给定选择器的元素出现在 DOM 中
  • 等待它变为显示状态，例如，非空，无 display:none，无 visibility:hidden
  • 等待它停止移动，例如，直到 CSS 过渡完成
  • 将元素滚动到视图中
  • 等待它在操作点接收指针事件，例如，等待直到元素不再被其他元素遮挡
  • 如果在上述任何检查期间元素被分离，则重试

强制点击​

有时，应用程序使用非平凡的逻辑，例如悬停元素时，另一个元素会覆盖并拦截点击。这种行为与元素被覆盖而点击被发送到其他位置的 bug 无法区分。如果您知道这种情况正在发生，您可以绕过可操作性检查并强制点击。

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

程序化点击​

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

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

输入字符​

注意

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

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

// Press keys one by one
page.locator("#area").pressSequentially("Hello World!");

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

按键和快捷键​

// Hit Enter
page.getByText("Submit").press("Enter");

// Dispatch Control+Right
page.getByRole(AriaRole.TEXTBOX).press("Control+ArrowRight");

// Press $ sign on keyboard
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, etc.
  • 或者，您可以指定一个要产生的单个字符，例如 "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" 的 input 元素。可以在数组中传递多个文件。如果某些文件路径是相对路径，它们会相对于当前工作目录进行解析。空数组会清除已选择的文件。

// Select one file
page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

// Select multiple files
page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

// Select a directory
page.getByLabel("Upload directory").setInputFiles(Paths.get("mydir"));

// Remove all the selected files
page.getByLabel("Upload file").setInputFiles(new Path[0]);

// Upload buffer from memory
page.getByLabel("Upload file").setInputFiles(new FilePayload(
  "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

如果您没有现成的 input 元素（它是动态创建的），您可以处理 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 会在执行任何操作之前自动为您滚动。因此，您无需显式滚动。

// Scrolls automatically so that button is visible
page.getByRole(AriaRole.BUTTON).click();

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

// Scroll the footer into view, forcing an "infinite list" to load more content
page.getByText("Footer text").scrollIntoViewIfNeeded();

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

// Position the mouse and scroll with the mouse wheel
page.getByTestId("scrolling-container").hover();
page.mouse.wheel(0, 10);

// Alternatively, programmatically scroll a specific element
page.getByTestId("scrolling-container").evaluate("e => e.scrollTop += 100");