Skip to main content

操作

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

Text input​

使用 locator.fill(value, **kwargs) 是填写表单字段的最简单方法。它聚焦元素并使用输入的文本触发 input 事件。它适用于 <input>、<textarea> 和 [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")

Checkboxes and radio buttons​

使用 locator.set_checked(checked, **kwargs) 是选中和取消选中复选框或单选按钮的最简单方法。此方法可用于 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
assert page.get_by_label('Subscribe to newsletter').is_checked() is True

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

Select options​

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

# Single selection matching the value
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'])

Mouse click​

执行简单的人工点击。

# 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 过渡完成
  • 将元素滚动到视图中
  • 等待它在操作点接收指针事件，例如，等待元素不再被其他元素遮挡
  • 如果在上述任何检查期间元素分离，则重试

Forcing the click​

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

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

Programmatic click​

如果您对在真实条件下测试您的应用程序不感兴趣，并且想通过任何可能的方式模拟点击，您可以通过使用 locator.dispatch_event(type, **kwargs) 在元素上简单地分派点击事件来触发 HTMLElement.click() 行为：

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

Type characters​

使用 locator.type(text, **kwargs) 逐个字符地输入字段，就像使用真实键盘的用户一样。

# Type character by character
page.locator('#area').type('Hello World!')

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

note

大多数时候，page.fill(selector, value, **kwargs) 就可以工作。只有在页面上有特殊的键盘处理时，您才需要输入字符。

Keys and shortcuts​

# 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(key, **kwargs) 方法聚焦选定的元素并产生单个击键。它接受在键盘事件的 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 一样。

Upload files​

您可以使用 locator.set_input_files(files, **kwargs) 方法选择要上传的输入文件。它期望第一个参数指向类型为 "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'])

# 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.locator("upload").click()
file_chooser = fc_info.value
file_chooser.set_files("myfile.pdf")

Focus element​

对于处理焦点事件的动态页面，您可以使用 locator.focus(**kwargs) 聚焦给定元素。

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

Drag and Drop​

您可以使用 locator.drag_to(target, **kwargs) 执行拖放操作。此方法将：

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

Dragging manually​

如果您想精确控制拖动操作，请使用更低级的方法，例如 locator.hover(**kwargs)、mouse.down(**kwargs)、mouse.move(x, y, **kwargs) 和 mouse.up(**kwargs)。

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

如果您的页面依赖于分派 dragover 事件，则至少需要两次鼠标移动才能在所有浏览器中触发它。要可靠地发出第二次鼠标移动，请重复您的 mouse.move(x, y, **kwargs) 或 locator.hover(**kwargs) 两次。操作顺序将是：悬停拖动元素，鼠标按下，悬停放置元素，第二次悬停放置元素，鼠标抬起。