Puppeteer Locator | BCTRL

All Locator methods available when using the Puppeteer driver.

Access via runtime.page.locator(...) after launching a Puppeteer runtime.

How these methods work over HTTP

Every method below is a remote call. The SDK translates it into a structured step sent to a single endpoint:

POST /v1/workspaces/{workspaceId}/execute

1 {
2   "runtime": "my-browser",
3   "steps": [
4     {
5       "call": "locator.goto",
6       "args": ["https://example.com"]
7     }
8   ]
9 }

The call field maps directly to the method name. args is a JSON array of the method’s arguments. You can batch multiple steps in one request.

Actions

click(options?)

Clicks the located element.

1 await runtime.page.locator(...).click();

Parameter	Type	Required	Description
`options`	`Readonly<PuppeteerLocatorClickOptions>`	No	—

Upstream docs

fill(value, options?)

Fills out the input identified by the locator.

The type of the input is determined at runtime and the appropriate fill-out method is chosen based on the type. contenteditable, select, textarea and input elements are supported.

1 await runtime.page.locator(...).fill('...');

Parameter	Type	Required	Description
`value`	`string`	Yes	—
`options`	`Readonly<PuppeteerActionOptions>`	No	—

Upstream docs

hover(options?)

Hovers over the located element.

1 await runtime.page.locator(...).hover();

Parameter	Type	Required	Description
`options`	`Readonly<PuppeteerActionOptions>`	No	—

Upstream docs

scroll(options?)

Scrolls the located element.

1 await runtime.page.locator(...).scroll();

Parameter	Type	Required	Description
`options`	`Readonly<PuppeteerLocatorScrollOptions>`	No	—

Upstream docs

Queries

filter(predicate)

Creates an expectation that is evaluated against located values.

If the expectations do not match, then the locator will retry. For RPC, the predicate function is serialized as a string.

1 // Filter to only enabled buttons
2 const enabledButton = page.locator('button')
3   .filter((el) => !el.disabled);

Parameter	Type	Required	Description
`predicate`	`LocatorPredicate<T, S> \| string`	Yes	—

Returns RemotePuppeteerLocator<S>

Upstream docs

Waiting

wait(options?)

Waits for the locator to get the serialized value from the page.

Note this requires the value to be JSON-serializable. If a mapper was applied via map(), returns the mapped value.

1 await runtime.page.locator(...).wait();

Parameter	Type	Required	Description
`options`	`Readonly<PuppeteerActionOptions>`	No	—

Returns T

Upstream docs

waitHandle(options?)

Waits for the locator to get a handle from the page.

1 await runtime.page.locator(...).waitHandle();

Parameter	Type	Required	Description
`options`	`Readonly<PuppeteerActionOptions>`	No	—

Returns RemotePuppeteerElementHandle

Upstream docs

Other

map(mapper)

Maps the locator using the provided mapper function.

For RPC, the mapper function is serialized as a string. The result is returned when wait() is called.

1 // Get the text content of an element
2 const text = await page.locator('h1')
3   .map((el) => el.textContent)
4   .wait();

Parameter	Type	Required	Description
`mapper`	`LocatorMapper<T, S> \| string`	Yes	—

Returns RemotePuppeteerLocator<S>

Upstream docs