puppeteer/website/versioned_docs/version-21.3.8/api/puppeteer.frame.md

sidebar_label
Frame

Frame class

Represents a DOM frame.

To understand frames, you can think of frames as <iframe> elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not effect frames inside the ambient frame the JavaScript executes in.

Signature:

export declare abstract class Frame extends EventEmitter<FrameEvents>

Extends: EventEmitter<FrameEvents>

Remarks

Frame lifecycles are controlled by three events that are all dispatched on the parent page:

• PageEvent.FrameAttached - PageEvent.FrameNavigated - PageEvent.FrameDetached

The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Frame class.

Example 1

At any point in time, pages expose their current frame tree via the Page.mainFrame() and Frame.childFrames() methods.

Example 2

An example of dumping frame tree:

import puppeteer from 'puppeteer';

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.google.com/chrome/browser/canary.html');
  dumpFrameTree(page.mainFrame(), '');
  await browser.close();

  function dumpFrameTree(frame, indent) {
    console.log(indent + frame.url());
    for (const child of frame.childFrames()) {
      dumpFrameTree(child, indent + '  ');
    }
  }
})();

Example 3

An example of getting text from an iframe element:

const frame = page.frames().find(frame => frame.name() === 'myframe');
const text = await frame.$eval('.selector', element => element.textContent);
console.log(text);

Properties

Property	Modifiers	Type	Description
detached	readonly	boolean

Methods

Method	Modifiers	Description
$(selector)		Queries the frame for an element matching the given selector.
$$(selector)		Queries the frame for all elements matching the given selector.
$$eval(selector, pageFunction, args)		Runs the given function on an array of elements matching the given selector in the frame. If the given function returns a promise, then this method will wait till the promise resolves.
$eval(selector, pageFunction, args)		Runs the given function on the first element matching the given selector in the frame. If the given function returns a promise, then this method will wait till the promise resolves.
$x(expression)
addScriptTag(options)		Adds a <script> tag into the page with the desired url or content.
addStyleTag(options)		Adds a HTMLStyleElement into the frame with the desired URL
addStyleTag(options)		Adds a HTMLLinkElement into the frame with the desired URL
childFrames()		An array of child frames.
click(selector, options)		Clicks the first element found that matches selector.
content()		The full HTML contents of the frame, including the DOCTYPE.
evaluate(pageFunction, args)		Behaves identically to Page.evaluate() except it's run within the the context of this frame.
evaluateHandle(pageFunction, args)		Behaves identically to Page.evaluateHandle() except it's run within the context of this frame.
focus(selector)		Focuses the first element that matches the selector.
goto(url, options)		Navigates the frame to the given url.
hover(selector)		Hovers the pointer over the center of the first element that matches the selector.
isDetached()		Istrue if the frame has been detached. Otherwise, false.
isOOPFrame()		Is true if the frame is an out-of-process (OOP) frame. Otherwise, false.
locator(selector)		Creates a locator for the provided selector. See Locator for details and supported actions.
locator(func)		Creates a locator for the provided function. See Locator for details and supported actions.
name()		The frame's name attribute as specified in the tag.
page()		The page associated with the frame.
parentFrame()		The parent frame, if any. Detached and main frames return null.
select(selector, values)		Selects a set of value on the first <select> element that matches the selector.
setContent(html, options)		Set the content of the frame.
tap(selector)		Taps the first element that matches the selector.
title()		The frame's title.
type(selector, text, options)		Sends a keydown, keypress/input, and keyup event for each character in the text.
url()		The frame's URL.
waitForDevicePrompt(options)		This method is typically coupled with an action that triggers a device request from an api such as WebBluetooth. :::caution This must be called before the device request is made. It will not return a currently active device prompt. :::
waitForFunction(pageFunction, options, args)
waitForNavigation(options)		Waits for the frame to navigate. It is useful for when you run code which will indirectly cause the frame to navigate. Usage of the History API to change the URL is considered a navigation.
waitForSelector(selector, options)		Waits for an element matching the given selector to appear in the frame. This method works across navigations.
waitForTimeout(milliseconds)
waitForXPath(xpath, options)