Implementation:Puppeteer Puppeteer Cdp Frame

Property	Value
sources	packages/puppeteer-core/src/cdp/Frame.ts
domains	Frame Management, Navigation, CDP
last_updated	2026-02-12 00:00 GMT

Overview

Description

The CdpFrame class is the CDP-specific implementation of the abstract Frame base class. It represents a single frame in the browser's frame tree (main frame or iframe) and provides methods for navigation, content manipulation, JavaScript evaluation, and lifecycle management.

Key responsibilities include:

• Navigation -- Navigating frames to URLs via Page.navigate CDP command with support for referrer, referrer policy, and wait conditions (load, domcontentloaded, networkidle0, networkidle2). Uses LifecycleWatcher to wait for navigation completion.
• Content management -- Setting frame HTML content via setContent() and reading the current URL.
• Execution worlds -- Maintaining two isolated worlds: MAIN_WORLD (the page's default execution context) and PUPPETEER_WORLD (an isolated context for Puppeteer's internal operations).
• Accessibility -- Providing an Accessibility instance scoped to the frame.
• Frame tree navigation -- Accessing parent and child frames via the FrameManager's frame tree.
• Lifecycle tracking -- Tracking loading states, lifecycle events (init, load, DOMContentLoaded), and loader IDs.
• Preload scripts and bindings -- Adding preload scripts and exposed function bindings to the frame.
• Device prompts -- Waiting for device request prompts (e.g., Bluetooth).
• Frame element -- Retrieving the ElementHandle for the frame's owner element (iframe element in the parent frame).

The class also contains a utility function referrerPolicyToProtocol() that converts web-facing referrer policy values to CDP's camelCase format.

Usage

CdpFrame instances are created by the FrameManager and accessed via page.mainFrame(), page.frames(), or through frame navigation events.

Code Reference

Source Location: packages/puppeteer-core/src/cdp/Frame.ts (452 lines)

Signature:

export class CdpFrame extends Frame {
  constructor(
    frameManager: FrameManager,
    frameId: string,
    parentFrameId: string | undefined,
    client: CDPSession,
  );

  override page(): CdpPage;
  override async goto(url: string, options?: {
    referer?: string;
    referrerPolicy?: string;
    timeout?: number;
    waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
  }): Promise<HTTPResponse | null>;
  override async waitForNavigation(options?: WaitForOptions): Promise<HTTPResponse | null>;
  override async setContent(html: string, options?: {
    timeout?: number;
    waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[];
  }): Promise<void>;
  override url(): string;
  override parentFrame(): CdpFrame | null;
  override childFrames(): CdpFrame[];
  override mainRealm(): IsolatedWorld;
  override isolatedRealm(): IsolatedWorld;
  override get client(): CDPSession;
  override get detached(): boolean;
  override async frameElement(): Promise<ElementHandle<HTMLIFrameElement> | null>;
}

Import:

import { CdpFrame } from 'puppeteer-core/lib/cdp/Frame.js';

I/O Contract

Inputs:

Parameter	Type	Required	Description
url	string	Yes	The URL to navigate to
options.referer	string	No	The referer header value
options.referrerPolicy	string	No	The referrer policy
options.timeout	number	No	Navigation timeout in ms
options.waitUntil	PuppeteerLifeCycleEvent[]	No	Lifecycle events to wait for (default: ['load'])
html	string	Yes	HTML content for setContent()

Outputs:

Output	Type	Description
goto() return	null>	The HTTP response of the navigation, or null
waitForNavigation() return	null>	The HTTP response of the next navigation
url()	string	The current URL of the frame
parentFrame()	null	The parent frame, or null for the main frame
childFrames()	CdpFrame[]	Array of child frames

Usage Examples

// Navigate the main frame
const response = await page.mainFrame().goto('https://example.com', {
  waitUntil: 'networkidle0',
  timeout: 30000,
});
console.log(response.status());

// Set frame content
await page.mainFrame().setContent('<h1>Hello World</h1>', {
  waitUntil: 'domcontentloaded',
});

// Wait for navigation
const [response] = await Promise.all([
  page.mainFrame().waitForNavigation(),
  page.click('a#link'),
]);

// Access child frames
const frames = page.mainFrame().childFrames();
for (const frame of frames) {
  console.log(frame.url());
}

// Evaluate in frame context
const title = await page.mainFrame().evaluate(() => document.title);

// Get the iframe element handle
const iframeHandle = await frame.frameElement();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime