puppeteer/docs/api/puppeteer.frame.md

sidebar_label
Frame

Frame class

At every point of time, page exposes its current frame tree via the page.mainFrame and frame.childFrames methods.

Signature:

export declare class Frame

Remarks

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

• PageEmittedEvents.FrameAttached - PageEmittedEvents.FrameNavigated - PageEmittedEvents.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

An example of dumping frame tree:

const puppeteer = require('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 2

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);

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 <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content.
childFrames()
click(selector, options)		Clicks the first element found that matches selector.
content()
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.
executionContext()
focus(selector)		Focuses the first element that matches the selector.
goto(url, options)		Navigates a frame to the given url.
hover(selector)		Hovers the pointer over the center of the first element that matches the selector.
isDetached()
isOOPFrame()
name()
page()
parentFrame()
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()
type(selector, text, options)		Sends a keydown, keypress/input, and keyup event for each character in the text.
url()
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)		Wait for an element matching the given selector to appear in the frame. This method works across navigations.
waitForTimeout(milliseconds)		Causes your script to wait for the given number of milliseconds.
waitForXPath(xpath, options)