Selectors
Selectors can be used to install custom selector engines. See extensibility for more information.
Methods
register
Added in: v1.8Selectors must be registered before creating the page.
Usage
An example of registering selector engine that queries elements based on a tag name:
// Script that evaluates to a selector engine instance. The script is evaluated in the page context.
String createTagNameEngine = "{\n" +
" // Returns the first element matching given selector in the root's subtree.\n" +
" query(root, selector) {\n" +
" return root.querySelector(selector);\n" +
" },\n" +
" // Returns all elements matching given selector in the root's subtree.\n" +
" queryAll(root, selector) {\n" +
" return Array.from(root.querySelectorAll(selector));\n" +
" }\n" +
"}";
// Register the engine. Selectors will be prefixed with "tag=".
playwright.selectors().register("tag", createTagNameEngine);
Browser browser = playwright.firefox().launch();
Page page = browser.newPage();
page.setContent("<div><button>Click me</button></div>");
// Use the selector prefixed with its name.
Locator button = page.locator("tag=button");
// Combine it with built-in locators.
page.locator("tag=div").getByText("Click me").click();
// Can use it in any methods supporting selectors.
int buttonCount = (int) page.locator("tag=button").count();
browser.close();
Arguments
-
Name that is used in selectors as a prefix, e.g.
{name: 'foo'}
enablesfoo=myselectorbody
selectors. May only contain[a-zA-Z0-9_]
characters. -
Script that evaluates to a selector engine instance. The script is evaluated in the page context.
-
options
Selectors.RegisterOptions
(optional)-
setContentScript
boolean (optional)#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.
-
setTestIdAttribute
Added in: v1.27Defines custom attribute name to be used in Page.getByTestId(). data-testid
is used by default.
Usage
Selectors.setTestIdAttribute(attributeName);
Arguments