Puppeteer Frame | BCTRL | Documentation

All Frame methods available when using the Puppeteer driver.

Access via frame 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": "frame.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.

goto(url, options?)

Navigate the frame to a URL.

1 await frame.goto('...');

Parameter	Type	Required	Description
`url`	`string`	Yes	—
`options`	`PuppeteerGotoOptions`	No	—

Returns PuppeteerHTTPResponse \| null

Upstream docs

waitForNavigation(options?)

Wait for navigation to complete.

1 await frame.waitForNavigation();

Parameter	Type	Required	Description
`options`	`PuppeteerWaitForNavigationOptions`	No	—

Returns PuppeteerHTTPResponse \| null

Upstream docs

Page Info

url()

The frame’s URL.

1 await frame.url();

Returns string

Upstream docs

title()

The frame’s title.

1 await frame.title();

Returns string

Upstream docs

content()

The full HTML contents of the frame.

1 await frame.content();

Returns string

Upstream docs

setContent(html, options?)

Set the content of the frame.

1 await frame.setContent('...');

Parameter	Type	Required	Description
`html`	`string`	Yes	—
`options`	`{ timeout?: number; waitUntil?: string }`	No	—

Upstream docs

Actions

click(selector, options?)

Click on an element.

1 await frame.click('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`options`	`PuppeteerClickOptions`	No	—

Upstream docs

type(selector, text, options?)

Type text into an element.

1 await frame.type('...', '...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`text`	`string`	Yes	—
`options`	`PuppeteerKeyboardTypeOptions`	No	—

Upstream docs

focus(selector)

Focus on an element.

1 await frame.focus('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—

Upstream docs

hover(selector)

Hover over an element.

1 await frame.hover('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—

Upstream docs

select(selector, …values)

Select options in a <select> element.

1 await frame.select('...', /* string[] */);

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`values`	`string[]`	Yes	—

Returns string[]

Upstream docs

tap(selector)

Tap on an element.

1 await frame.tap('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—

Upstream docs

Queries

page()

The page associated with this frame.

Returns the cached page reference passed at construction time.

1 frame.page();

Returns RemotePuppeteerPage \| null

Upstream docs

locator(selector)

Creates a Locator for the given selector.

Locators are used for performing actions on elements with built-in waiting.

1 frame.locator('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—

Returns RemotePuppeteerLocator

Upstream docs

$(selector)

Query for a single element.

1 await frame.$('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—

Returns RemotePuppeteerElementHandle \| null

Upstream docs

$$(selector)

Query for all matching elements.

1 await frame.$$('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—

Returns RemotePuppeteerElementHandle[]

Upstream docs

$x(expression)

Evaluate XPath expression. (Uses $$() with xpath prefix internally)

1 await frame.$x('...');

Parameter	Type	Required	Description
`expression`	`string`	Yes	—

Returns RemotePuppeteerElementHandle[]

Upstream docs

State Checks

isDetached()

Whether this frame is detached.

@deprecated Use the detached getter.

1 frame.isDetached();

Returns boolean

Upstream docs

isMainFrame()

Is this the main frame?

1 await frame.isMainFrame();

Returns boolean

Upstream docs

isOOPFrame()

Is this an out-of-process frame? (Deprecated - always returns false)

1 await frame.isOOPFrame();

Returns boolean

Upstream docs

Waiting

waitForSelector(selector, options?)

Wait for a selector to appear.

1 await frame.waitForSelector('...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`options`	`PuppeteerWaitForSelectorOptions`	No	—

Returns RemotePuppeteerElementHandle \| null

Upstream docs

waitForFunction(pageFunction, options?, …args)

Wait for a function to return a truthy value.

1 await frame.waitForFunction('...');

Parameter	Type	Required	Description
`pageFunction`	`Func \| string`	Yes	—
`options`	`{ timeout?: number; polling?: number \| 'raf' \| 'mutation' }`	No	—
`args`	`Params`	No	—

Returns RemotePuppeteerJSHandle<Awaited<ReturnType<Func>>>

Upstream docs

Evaluation

evaluate(pageFunction, …args)

Evaluate JavaScript in the frame context.

1 await frame.evaluate('...');

Parameter	Type	Required	Description
`pageFunction`	`string \| ((...args: unknown[]) => T \| Promise<T>)`	Yes	—
`args`	`unknown[]`	No	—

Returns T

Upstream docs

$eval(selector, pageFunction, …args)

Evaluate JavaScript on a selected element.

1 await frame.$eval('...', '...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`pageFunction`	`string \| ((el: Element, ...args: unknown[]) => T \| Promise<T>)`	Yes	—
`args`	`unknown[]`	No	—

Returns T

Upstream docs

$$eval(selector, pageFunction, …args)

Evaluate JavaScript on all matching elements.

1 await frame.$$eval('...', '...');

Parameter	Type	Required	Description
`selector`	`string`	Yes	—
`pageFunction`	`string \| ((els: Element[], ...args: unknown[]) => T \| Promise<T>)`	Yes	—
`args`	`unknown[]`	No	—

Returns T

Upstream docs

evaluateHandle(pageFunction, …args)

Evaluates a function in the frame’s context and returns a handle to the result.

1 await frame.evaluateHandle('...');

Parameter	Type	Required	Description
`pageFunction`	`Func \| string`	Yes	—
`args`	`Params`	No	—

Returns RemotePuppeteerJSHandle<Awaited<ReturnType<Func>>>

Upstream docs

Other

detached()

Is true if the frame has been detached. Otherwise, false.

1 frame.detached();

Returns boolean

Upstream docs

frameElement()

The frame element associated with this frame, if any.

Returns the ElementHandle for the <iframe> or <frame> tag for this frame. Returns null for the main frame.

1 await frame.frameElement();

Returns RemotePuppeteerElementHandle \| null

Upstream docs

name()

The frame’s name attribute as specified in the tag.

1 await frame.name();

Returns string

Upstream docs

parentFrame()

The parent frame, if any.

Returns null for the main frame.

1 await frame.parentFrame();

Returns RemotePuppeteerFrame \| null

Upstream docs

childFrames()

Child frames of this frame.

1 await frame.childFrames();

Returns RemotePuppeteerFrame[]

Upstream docs

addScriptTag(options)

Add a script tag to the frame.

1 await frame.addScriptTag(/* PuppeteerFrameAddScriptTagOptions */);

Parameter	Type	Required	Description
`options`	`PuppeteerFrameAddScriptTagOptions`	Yes	—

Returns RemotePuppeteerElementHandle

Upstream docs

addStyleTag(options)

Add a style tag to the frame.

1 await frame.addStyleTag(/* PuppeteerFrameAddStyleTagOptions */);

Parameter	Type	Required	Description
`options`	`PuppeteerFrameAddStyleTagOptions`	Yes	—

Returns RemotePuppeteerElementHandle

Upstream docs