Implementation:Puppeteer Puppeteer Frame Goto

Knowledge Sources	Puppeteer Puppeteer API
Domains	Browser_Automation, Web_Navigation
Last Updated	2026-02-11 23:00 GMT

Overview

Concrete tool for navigating a browser frame to a specified URL, provided by the puppeteer-core library.

Description

The Frame.goto() method navigates a frame to the given URL. Since Page delegates to its main frame, page.goto(url) is equivalent to page.mainFrame().goto(url). The method supports configurable wait conditions and timeouts, and returns the HTTP response for the main resource.

This is an abstract method on the Frame base class, implemented by both CDP (CdpFrame) and BiDi (BidiFrame) backends.

Usage

Call this method to load a URL into a page or frame. It is the standard way to navigate to web pages in Puppeteer scripts.

Code Reference

Source Location

Repository: puppeteer
File: packages/puppeteer-core/src/api/Frame.ts
Lines: 352-355

Signature

abstract class Frame {
  abstract goto(
    url: string,
    options?: GoToOptions,
  ): Promise<HTTPResponse | null>;
}

Import

// Frame.goto() is accessed through a Page instance
const page = await browser.newPage();
await page.goto(url, options);  // delegates to page.mainFrame().goto()

I/O Contract

Inputs

Name	Type	Required	Description
url	string	Yes	The URL to navigate to. Must include protocol (e.g., https://)
options	GoToOptions	No	Navigation configuration
options.waitUntil	PuppeteerLifeCycleEvent	No	When to consider navigation complete: 'load', 'domcontentloaded', 'networkidle0', 'networkidle2'
options.timeout	number	No	Maximum navigation time in milliseconds (default: 30000)
options.referer	string	No	Referer header value

Outputs

Name	Type	Description
return	Promise<HTTPResponse or null>	The main resource response, or null if navigation results in a different URL (e.g., anchor navigation)

Usage Examples

Basic Navigation

const page = await browser.newPage();
const response = await page.goto('https://example.com');
console.log(response.status()); // 200

Wait For Network Idle

// Wait until no network requests for 500ms - useful for SPAs
await page.goto('https://example.com', {
  waitUntil: 'networkidle0',
  timeout: 60000,
});

Navigate With Multiple Wait Conditions

// Wait for both DOM and network idle
await page.goto('https://example.com', {
  waitUntil: ['domcontentloaded', 'networkidle2'],
});

Related Pages

Implements Principle

Principle:Puppeteer_Puppeteer_Page_Navigation

Requires Environment

Environment:Puppeteer_Puppeteer_Node_18_Runtime

Uses Heuristic

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment