Skip to main content

Selectors

选择器可用于安装自定义选择器引擎。请参阅 extensibility 了解更多信息。

¥Selectors can be used to install custom selector engines. See extensibility for more information.

方法​

¥Methods

register​

Added in: v1.8 selectors.register

创建页面之前必须注册选择器。

¥Selectors must be registered before creating the page.

用法

¥Usage

注册根据标签名称查询元素的选择器引擎的示例：

¥An example of registering selector engine that queries elements based on a tag name:

const { selectors, firefox } = require('@playwright/test');  // Or 'chromium' or 'webkit'.

(async () => {
  // Must be a function that evaluates to a selector engine instance.
  const createTagNameEngine = () => ({
    // Returns the first element matching given selector in the root's subtree.
    query(root, selector) {
      return root.querySelector(selector);
    },

    // Returns all elements matching given selector in the root's subtree.
    queryAll(root, selector) {
      return Array.from(root.querySelectorAll(selector));
    }
  });

  // Register the engine. Selectors will be prefixed with "tag=".
  await selectors.register('tag', createTagNameEngine);

  const browser = await firefox.launch();
  const page = await browser.newPage();
  await page.setContent(`<div><button>Click me</button></div>`);

  // Use the selector prefixed with its name.
  const button = page.locator('tag=button');
  // We can combine it with built-in locators.
  await page.locator('tag=div').getByText('Click me').click();
  // Can use it in any methods supporting selectors.
  const buttonCount = await page.locator('tag=button').count();

  await browser.close();
})();

参数

¥Arguments

在选择器中用作前缀的名称，例如 {name: 'foo'} 启用 foo=myselectorbody 选择器。只能包含 [a-zA-Z0-9_] 个字符。

¥Name that is used in selectors as a prefix, e.g. {name: 'foo'} enables foo=myselectorbody selectors. May only contain [a-zA-Z0-9_] characters.

JavaScript 文件的路径。如果 path 是相对路径，则相对于当前工作目录进行解析。可选的。

¥Path to the JavaScript file. If path is a relative path, then it is resolved relative to the current working directory. Optional.

原始脚本内容。可选的。

¥Raw script content. Optional.

计算结果为选择器引擎实例的脚本。该脚本在页面上下文中进行评估。

¥Script that evaluates to a selector engine instance. The script is evaluated in the page context.

是否在隔离的 JavaScript 环境中运行此选择器引擎。此环境可以访问相同的 DOM，但不能访问框架脚本中的任何 JavaScript 对象。默认为 false。请注意，当该引擎与其他注册引擎一起使用时，不能保证作为内容脚本运行。

¥Whether to run this selector engine in isolated JavaScript environment. This environment has access to the same DOM, but not any JavaScript objects from the frame's scripts. Defaults to false. Note that running as a content script is not guaranteed when this engine is used together with other registered engines.

返回

¥Returns

setTestIdAttribute​

Added in: v1.27 selectors.setTestIdAttribute

定义要在 page.getByTestId() 中使用的自定义属性名称。默认使用 data-testid。

¥Defines custom attribute name to be used in page.getByTestId(). data-testid is used by default.

用法

¥Usage

selectors.setTestIdAttribute(attributeName);

参数

¥Arguments

测试 id 属性名称。

¥Test id attribute name.