custom$
Overview
Find an element with a custom locator strategy, passing the parent element as the final strategy argument. Make the strategy search inside that element to limit its scope.
Usage
element.custom$(strategyName, ...strategyArguments)
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
strategyName | string | Required | Name registered with browser.addLocatorStrategy. |
strategyArguments | unknown[] | [] | Arguments passed before the parent DOM element. |
Result
An awaitable element object. If the strategy returns an array, only its first element is used. A result without a match has no elementId.
Limitations
Register the strategy on the same browser instance. The parent must exist; an unknown strategy or missing parent causes an error. The callback runs in the browser and must return a DOM element or an array of DOM elements. Convert a NodeList with Array.from. Scoping is the callback’s responsibility: using document.querySelector still searches the whole document. This command does not wait for a particular number of children or for visibility.
Example
Set baseUrl to a local HTTP test site where / serves an HTML page. Run the example in a Testplane test file.
const assert = require("node:assert/strict");
it("element.custom$: search inside an element", async ({ browser }) => {
await browser.url("/");
await browser.execute(() => {
document.body.innerHTML =
'<button data-test="save">Outside</button><section id="panel"><button data-test="save">Inside</button></section>';
});
browser.addLocatorStrategy("byTestWithin", (value, root) =>
root.querySelector(`[data-test="${value}"]`),
);
const button = await browser.$("#panel").custom$("byTestWithin", "save");
assert.equal(await button.getText(), "Inside");
});