Skip to main content

操作

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

文本输入​

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

// 文本输入
await page.getByRole('textbox').fill('Peter');

// 日期输入
await page.getByLabel('Birth date').fill('2020-02-02');

// 时间输入
await page.getByLabel('Appointment time').fill('13:15');

// 本地日期时间输入
await page.getByLabel('Local time').fill('2020-03-02T05:15');

复选框和单选按钮​

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

// 选中复选框
await page.getByLabel('I agree to the terms above').check();

// 断言选中状态
expect(await page.getByLabel('Subscribe to newsletter').isChecked()).toBeTruthy()

// 选择单选按钮
await page.getByLabel('XL').check();

选择选项​

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

// 匹配值的单选
await page.getByLabel('Choose a color').selectOption('blue');

// 匹配标签的单选
await page.getByLabel('Choose a color').selectOption({ label: 'Blue' });

// 多选项目
await page.getByLabel('Choose multiple colors').selectOption(['red', 'green', 'blue']);

鼠标点击​

执行简单的人工点击。

// 通用点击
await page.getByRole('button').click();

// 双击
await page.getByText('Item').dblclick();

// 右键点击
await page.getByText('Item').click({ button: 'right' });

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

// 悬停在元素上
await page.getByText('Item').hover();

// 点击左上角
await page.getByText('Item').click({ position: { x: 0, y: 0} });

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

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

强制点击​

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

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

编程点击​

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

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

键入字符​

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

// 逐个字符键入
await page.locator('#area').type('Hello World!');

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

note

大多数情况下，page.fill(selector, value[, options]) 就可以工作。只有在页面上有特殊的键盘处理时，您才需要键入字符。

按键和快捷键​

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

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

// 按键盘上的 $ 符号
await page.getByRole('textbox').press('$');

locator.press(key[, options]) 方法聚焦选定的元素并产生单个击键。它接受在键盘事件的 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(files[, options]) 方法选择要上传的输入文件。它期望第一个参数指向类型为 "file" 的 input 元素。可以在数组中传递多个文件。如果某些文件路径是相对的，则它们是相对于当前工作目录解析的。空数组清除选定的文件。

// 选择一个文件
await page.getByLabel('Upload file').setInputFiles('myfile.pdf');

// 选择多个文件
await page.getByLabel('Upload files').setInputFiles(['file1.txt', 'file2.txt']);

// 移除所有选定的文件
await page.getByLabel('Upload file').setInputFiles([]);

// 从内存上传缓冲区
await page.getByLabel('Upload file').setInputFiles({
  name: 'file.txt',
  mimeType: 'text/plain',
  buffer: Buffer.from('this is test')
});

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

// 请注意，Promise.all 防止了点击和等待文件选择器之间的竞争条件。
const [fileChooser] = await Promise.all([
  // 重要的是在点击之前调用 waitForEvent 以设置等待。
  page.waitForEvent('filechooser'),
  page.locator('upload').click(),
]);
await fileChooser.setFiles('myfile.pdf');

聚焦元素​

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

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

拖放​

您可以使用 locator.dragTo(target[, options]) 执行拖放操作。此方法将：

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

手动拖动​

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

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

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