跳至主要内容

操作

简介​

Playwright can interact with HTML Input elements such as text inputs, checkboxes, radio buttons, select options, mouse clicks, type characters, keys and shortcuts as well as upload files and focus elements.

文本输入​

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

# Text input
page.get_by_role("textbox").fill("Peter")

# Date input
page.get_by_label("Birth date").fill("2020-02-02")

# Time input
page.get_by_label("Appointment time").fill("13:15")

# Local datetime input
page.get_by_label("Local time").fill("2020-03-02T05:15")

复选框和单选按钮​

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

# Check the checkbox
page.get_by_label('I agree to the terms above').check()

# Assert the checked state
expect(page.get_by_label('Subscribe to newsletter')).to_be_checked()

# Select the radio button
page.get_by_label('XL').check()

选择选项​

使用locator.select_option()在元素中选择一个或多个选项。您可以指定选项的value或label来进行选择。支持选择多个选项。

# Single selection matching the value or label
page.get_by_label('Choose a color').select_option('blue')

# Single selection matching the label
page.get_by_label('Choose a color').select_option(label='Blue')

# Multiple selected items
page.get_by_label('Choose multiple colors').select_option(['red', 'green', 'blue'])

鼠标点击​

执行一个简单的人工点击。

# Generic click
page.get_by_role("button").click()

# Double click
page.get_by_text("Item").dblclick()

# Right click
page.get_by_text("Item").click(button="right")

# Shift + click
page.get_by_text("Item").click(modifiers=["Shift"])

# Hover over element
page.get_by_text("Item").hover()

# Click the top left corner
page.get_by_text("Item").click(position={ "x": 0, "y": 0})

在底层实现上，这个以及其他与指针相关的方法：

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

强制点击​

有时，应用程序会使用非简单的逻辑，当悬停在元素上时会用另一个拦截点击的元素覆盖它。这种行为与元素被覆盖且点击被分发到其他位置的错误无法区分。如果您知道这种情况正在发生，可以绕过actionability检查并强制点击：

page.get_by_role("button").click(force=True)

编程式点击​

If you are not interested in testing your app under the real conditions and want to simulate the click by any means possible, you can trigger the HTMLElement.click() behavior via simply dispatching a click event on the element with locator.dispatch_event():

page.get_by_role("button").dispatch_event('click')

输入字符​

caution

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

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

# Press keys one by one
page.locator('#area').press_sequentially('Hello World!')

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

按键与快捷键​

# Hit Enter
page.get_by_text("Submit").press("Enter")

# Dispatch Control+Right
page.get_by_role("textbox").press("Control+ArrowRight")

# Press $ sign on keyboard
page.get_by_role("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.set_input_files()方法选择要上传的输入文件。该方法期望第一个参数指向一个类型为"file"的input元素。可以在数组中传递多个文件。如果某些文件路径是相对路径，它们将相对于当前工作目录进行解析。空数组会清除已选文件。

# Select one file
page.get_by_label("Upload file").set_input_files('myfile.pdf')

# Select multiple files
page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt'])

# Select a directory
page.get_by_label("Upload directory").set_input_files('mydir')

# Remove all the selected files
page.get_by_label("Upload file").set_input_files([])

# Upload buffer from memory
page.get_by_label("Upload file").set_input_files(
    files=[
        {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"}
    ],
)

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

with page.expect_file_chooser() as fc_info:
    page.get_by_label("Upload file").click()
file_chooser = fc_info.value
file_chooser.set_files("myfile.pdf")

聚焦元素​

对于处理焦点事件的动态页面，您可以使用locator.focus()将焦点设置在给定元素上。

page.get_by_label('password').focus()

拖放​

您可以使用locator.drag_to()执行拖放操作。该方法将：

  • 悬停在将被拖动的元素上。
  • 按下鼠标左键。
  • 将鼠标移动到将接收拖放的元素上。
  • 释放鼠标左键。
page.locator("#item-to-be-dragged").drag_to(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()
note

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

滚动​

大多数情况下，Playwright在执行任何操作前会自动为您滚动页面。因此，您不需要显式地进行滚动操作。

# Scrolls automatically so that button is visible
page.get_by_role("button").click()

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

# Scroll the footer into view, forcing an "infinite list" to load more content
page.get_by_text("Footer text").scroll_into_view_if_needed()

如果您想更精确地控制滚动，请使用 mouse.wheel() 或 locator.evaluate()：

# Position the mouse and scroll with the mouse wheel
page.get_by_test_id("scrolling-container").hover()
page.mouse.wheel(0, 10)

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