跳到主要内容

操作

简介​

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

文本输入​

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

# 文本输入
page.get_by_role("textbox").fill("Peter")

# 日期输入
page.get_by_label("Birth date").fill("2020-02-02")

# 时间输入
page.get_by_label("Appointment time").fill("13:15")

# 本地时间输入
page.get_by_label("Local time").fill("2020-03-02T05:15")

复选框和单选按钮​

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

# 勾选复选框
page.get_by_label('I agree to the terms above').check()

# 断言勾选状态
expect(page.get_by_label('Subscribe to newsletter')).to_be_checked()

# 选择单选按钮
page.get_by_label('XL').check()

选择选项​

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

# 按值或标签选择单项
page.get_by_label('Choose a color').select_option('blue')

# 按标签选择单项
page.get_by_label('Choose a color').select_option(label='Blue')

# 选择多项
page.get_by_label('Choose multiple colors').select_option(['red', 'green', 'blue'])

鼠标点击​

执行一个简单的鼠标点击操作。

# 基本点击
page.get_by_role("button").click()

# 双击
page.get_by_text("Item").dblclick()

# 右键点击
page.get_by_text("Item").click(button="right")

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

# 悬停元素
page.get_by_text("Item").hover()

# 点击左上角
page.get_by_text("Item").click(position={ "x": 0, "y": 0})

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

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

强制点击​

有时，应用程序使用非平凡的逻辑，当悬停元素时，它会在其上方覆盖另一个拦截点击的元素。这种行为与元素被遮挡且点击被分派到其他地方的 bug 无法区分。如果你知道正在发生这种情况，可以绕过可操作性 检查并强制点击：

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

编程点击​

如果你不关心在真实条件下测试你的应用，并希望用任何可能的方式模拟点击，可以通过简单地向元素发送点击事件来触发 HTMLElement.click() 行为，使用 locator.dispatch_event()：

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

输入字符​

警告

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

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

# 逐个按下键
page.locator('#area').press_sequentially('Hello World!')

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

键盘和快捷键​

# 按下回车键
page.get_by_text("Submit").press("Enter")

# 发送 Control+右箭头
page.get_by_role("textbox").press("Control+ArrowRight")

# 按下键盘上的 $ 符号
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 等等。
  • 你也可以指定一个你想生成的单个字符，比如 "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 元素。可以传递数组中的多个文件。如果某些文件路径是相对的，则相对于当前工作目录解析。空数组清除所选文件。

# 选择一个文件
page.get_by_label("Upload file").set_input_files('myfile.pdf')

# 选择多个文件
page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt'])

# 选择一个目录
page.get_by_label("Upload directory").set_input_files('mydir')

# 移除所有已选文件
page.get_by_label("Upload file").set_input_files([])

# 从内存上传缓冲区
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()
备注

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

滚动​

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

# 自动滚动以使按钮可见
page.get_by_role("button").click()

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

# 滚动页脚以加载更多内容
page.get_by_text("Footer text").scroll_into_view_if_needed()

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

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

# 或者编程方式滚动特定元素
page.get_by_test_id("scrolling-container").evaluate("e => e.scrollTop += 100")