Class Frame

A frame of the page (the main frame or an iframe), as returned by Page.frames, Page.waitForFrame, ElementHandle.contentFrame and ElementHandle.frame.

pjsc differences:

A Frame object is valid within one request. A call on a frame that has detached fails.
The synchronous members (url, name, parentFrame, childFrames, isDetached, detached, page, locator) read pjsc's copy of the frame tree, which is kept current as frames attach, detach and navigate.
Calls on the main frame wait until pjsc's own navigation to the request url has finished, except waitForNavigation, waitForSelector and waitForFunction.
addScriptTag / addStyleTag refuse path (no server file is read into the page).
waitForNavigation, waitForSelector and waitForFunction end with the render; their signal option is ignored. waitForFunction's root option must be an :class of the same request.

const frame = page.frames().find((f) => f.name() === "content");
await frame.click("#next");
page.meta.log(await frame.title());

Index

Properties

`Readonly`detached

detached: boolean

true once the frame has detached

Methods

$

$(selector: string): Promise<ElementHandle>
The first element matching selector in the frame, or null.
Parameters
- selector: string
Returns Promise<ElementHandle>

$$

$$(selector: string): Promise<ElementHandle[]>
Every element matching selector in the frame.
Parameters
- selector: string
Returns Promise<ElementHandle[]>

$$eval

$$eval(
    selector: string,
    pageFunction: PageFunction,
    ...args: any[],
): Promise<any>
Runs pageFunction(elements, ...args) on every element matching selector.
Parameters
- selector: string
- pageFunction: PageFunction
- ...args: any[]
Returns Promise<any>

$eval

$eval(
    selector: string,
    pageFunction: PageFunction,
    ...args: any[],
): Promise<any>
Runs pageFunction(element, ...args) on the first element matching selector; fails when none matches.
Parameters
- selector: string
- pageFunction: PageFunction
- ...args: any[]
Returns Promise<any>

addScriptTag

addScriptTag(
options: { content?: string; id?: string; type?: string; url?: string },
): Promise<ElementHandle>
Adds a <script> from url or content and returns its element. path is refused.
Parameters
- options: { content?: string; id?: string; type?: string; url?: string }
  url, content, type, id
Returns Promise<ElementHandle>

addStyleTag

addStyleTag(options: { content?: string; url?: string }): Promise<ElementHandle>
Adds a <link rel="stylesheet"> from url or a <style> from content and returns its element. path is refused.
Parameters
- options: { content?: string; url?: string }
Returns Promise<ElementHandle>

childFrames

childFrames(): Frame[]

The frame's child frames (synchronous).

Returns Frame[]

click

click(selector: string, options?: ClickOptions): Promise<void>
Clicks the first element matching selector.
Parameters
- selector: string
- Optionaloptions: ClickOptions
Returns Promise<void>

content

content(): Promise<string>

The frame's full HTML.

Returns Promise<string>

evaluate

evaluate(pageFunction: PageFunction, ...args: any[]): Promise<any>
Runs pageFunction in the frame and returns its result as JSON.
Parameters
- pageFunction: PageFunction
- ...args: any[]
  JSON values or handles passed to pageFunction
Returns Promise<any>

evaluateHandle

evaluateHandle(pageFunction: PageFunction, ...args: any[]): Promise<JSHandle>
Runs pageFunction in the frame and returns its result as a :class.
Parameters
- pageFunction: PageFunction
- ...args: any[]
Returns Promise<JSHandle>

focus

focus(selector: string): Promise<void>
Focuses the first element matching selector.
Parameters
- selector: string
Returns Promise<void>

frameElement

frameElement(): Promise<ElementHandle>

The <iframe> / <frame> element of this frame in its parent, or null for the main frame.

Returns Promise<ElementHandle>

goto

goto(
url: string,
options?: NavigationOptions & { referer?: string },
): Promise<HTTPResponse>
Navigates the frame to url and returns the main resource's response (:class, null for same-document navigations).
Parameters
- url: string
- Optionaloptions: NavigationOptions & { referer?: string }
  timeout, waitUntil, referer
Returns Promise<HTTPResponse>

hover

hover(selector: string): Promise<void>
Hovers the first element matching selector.
Parameters
- selector: string
Returns Promise<void>

isDetached

isDetached(): boolean

Whether the frame has detached (synchronous).

Returns boolean

locator

locator(selectorOrFunction: PageFunction): Locator
Creates a :class for selectorOrFunction in this frame (synchronous); see Page.locator.
Parameters
- selectorOrFunction: PageFunction
Returns Locator

name

name(): string

The frame's name attribute, or "" (synchronous).

Returns string

parentFrame

parentFrame(): Frame

The parent frame, or null for the main frame and detached frames (synchronous).

Returns Frame

select

select(selector: string, ...values: string[]): Promise<string[]>
Selects values in the first <select> matching selector; returns the selected values.
Parameters
- selector: string
- ...values: string[]
Returns Promise<string[]>

setContent

setContent(html: string, options?: NavigationOptions): Promise<void>
Replaces the frame's document with html.
Parameters
- html: string
- Optionaloptions: NavigationOptions
  timeout, waitUntil as for Page.setContent
Returns Promise<void>

tap

tap(selector: string): Promise<void>
Taps the first element matching selector.
Parameters
- selector: string
Returns Promise<void>

title

title(): Promise<string>

The frame document's title.

Returns Promise<string>

type

type(
    selector: string,
    text: string,
    options?: { delay?: number },
): Promise<void>
Focuses the first element matching selector and types text.
Parameters
- selector: string
- text: string
- Optionaloptions: { delay?: number }
  delay between key presses in milliseconds
Returns Promise<void>

url

url(): string

The frame's url (synchronous).

Returns string

waitForFunction

waitForFunction(
    pageFunction: PageFunction,
    options?: PageFnOptions,
    ...args: any[],
): Promise<JSHandle>
Waits until pageFunction returns a truthy value in the frame and returns that value as a :class. Does not wait for pjsc's own navigation first.
Parameters
- pageFunction: PageFunction
- Optionaloptions: PageFnOptions
  timeout, polling ("raf", "mutation" or milliseconds)
- ...args: any[]
Returns Promise<JSHandle>

waitForNavigation

waitForNavigation(options?: NavigationOptions): Promise<HTTPResponse>
Waits for the frame's next navigation and returns its response (:class or null). Does not wait for pjsc's own navigation first.
Parameters
- Optionaloptions: NavigationOptions
Returns Promise<HTTPResponse>

waitForSelector

waitForSelector(
selector: string,
options?: WaitForSelectorOptions,
): Promise<ElementHandle>
Waits for an element matching selector and returns it (null when waiting for hidden). Does not wait for pjsc's own navigation first.
Parameters
- selector: string
- Optionaloptions: WaitForSelectorOptions
Returns Promise<ElementHandle>

Class Frame

Index

Properties

Methods

Properties

Readonlydetached

Methods

$

Parameters

Returns Promise<ElementHandle>

$$

Parameters

Returns Promise<ElementHandle[]>

$$eval

Parameters

Returns Promise<any>

$eval

Parameters

Returns Promise<any>

addScriptTag

Parameters

Returns Promise<ElementHandle>

addStyleTag

Parameters

Returns Promise<ElementHandle>

childFrames

Returns Frame[]

click

Parameters

Returns Promise<void>

content

Returns Promise<string>

evaluate

Parameters

Returns Promise<any>

evaluateHandle

Parameters

Returns Promise<JSHandle>

focus

Parameters

Returns Promise<void>

frameElement

Returns Promise<ElementHandle>

goto

Parameters

Returns Promise<HTTPResponse>

hover

Parameters

Returns Promise<void>

isDetached

Returns boolean

locator

Parameters

Returns Locator

name

Returns string

page

Returns any

parentFrame

Returns Frame

select

Parameters

Returns Promise<string[]>

setContent

Parameters

Returns Promise<void>

tap

Parameters

Returns Promise<void>

title

Returns Promise<string>

type

Parameters

Returns Promise<void>

url

Returns string

waitForFunction

Parameters

Returns Promise<JSHandle>

waitForNavigation

`Readonly`detached