跳到主要内容

动作

介绍​

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

文本输入​

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

// Text input
await page.getByRole('textbox').fill('Peter');

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

// Time input
await page.getByLabel('Appointment time').fill('13:15');

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

复选框和单选按钮​

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

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

// Assert the checked state
expect(page.getByLabel('Subscribe to newsletter')).toBeChecked();

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

选择选项​

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

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

// Single selection matching the label
await page.getByLabel('Choose a color').selectOption({ label: 'Blue' });

// Multiple selected items
await page.getByLabel('Choose multiple colors').selectOption(['red', 'green', 'blue']);

鼠标点击​

执行简单的用户点击。

// Generic click
await page.getByRole('button').click();

// Double click
await page.getByText('Item').dblclick();

// Right click
await page.getByText('Item').click({ button: 'right' });

// Shift + click
await page.getByText('Item').click({ modifiers: ['Shift'] });

// Ctrl + click on Windows and Linux
// Meta + click on macOS
await page.getByText('Item').click({ modifiers: ['ControlOrMeta'] });

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

// Click the top left corner
await page.getByText('Item').click({ position: { x: 0, y: 0 } });

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

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

强制点击​

有时，应用程序使用复杂的逻辑，当鼠标悬停在元素上时，另一个元素会覆盖在其上并拦截点击。这种行为与元素被覆盖导致点击发送到其他位置的 bug 无法区分。如果你知道这种情况发生，你可以绕过操作性 (actionability) 检查并强制点击。

await page.getByRole('button').click({ force: true });

程序化点击​

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

await page.getByRole('button').dispatchEvent('click');

输入字符​

注意

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

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

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

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

按键和快捷键​

// Hit Enter
await page.getByText('Submit').press('Enter');

// Dispatch Control+Right
await page.getByRole('textbox').press('Control+ArrowRight');

// Press $ sign on keyboard
await page.getByRole('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>
await page.locator('#name').press('Shift+A');

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

还支持 "Control+o" 或 "Control+Shift+T" 等快捷键。与修饰符一起指定时，修饰符会在按下后续按键时被按下并保持。

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

上传文件​

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

// Select one file
await page.getByLabel('Upload file').setInputFiles(path.join(__dirname, 'myfile.pdf'));

// Select multiple files
await page.getByLabel('Upload files').setInputFiles([
  path.join(__dirname, 'file1.txt'),
  path.join(__dirname, 'file2.txt'),
]);

// Select a directory
await page.getByLabel('Upload directory').setInputFiles(path.join(__dirname, 'mydir'));

// Remove all the selected files
await page.getByLabel('Upload file').setInputFiles([]);

// Upload buffer from memory
await page.getByLabel('Upload file').setInputFiles({
  name: 'file.txt',
  mimeType: 'text/plain',
  buffer: Buffer.from('this is test')
});

如果你手上没有 input 元素（它是动态创建的），你可以处理 page.on('filechooser') 事件或在你的操作后使用相应的等待方法。

// Start waiting for file chooser before clicking. Note no await.
const fileChooserPromise = page.waitForEvent('filechooser');
await page.getByLabel('Upload file').click();
const fileChooser = await fileChooserPromise;
await fileChooser.setFiles(path.join(__dirname, 'myfile.pdf'));

聚焦元素​

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

await page.getByLabel('Password').focus();

拖放​

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

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

手动拖动​

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

await page.locator('#item-to-be-dragged').hover();
await page.mouse.down();
await page.locator('#item-to-drop-at').hover();
await page.mouse.up();
注意

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

滚动​

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

// Scrolls automatically so that button is visible
await page.getByRole('button').click();

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

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

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

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

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