Principle:Puppeteer Puppeteer Page Navigation
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Web_Navigation |
| Last Updated | 2026-02-11 23:00 GMT |
Overview
A mechanism that directs a browser page to load a specified URL and waits for a configurable lifecycle event before resolving.
Description
Page Navigation is the process of instructing a browser tab to load a web resource at a given URL. The navigation lifecycle involves DNS resolution, TCP connection, TLS handshake, HTTP request/response, HTML parsing, sub-resource loading, and JavaScript execution.
A critical aspect of navigation in automation is determining when the page is considered "loaded." Different automation scenarios require different wait conditions:
- load: Fires when the full page (including images and stylesheets) has loaded
- domcontentloaded: Fires when the HTML has been parsed without waiting for stylesheets/images
- networkidle0: Fires when there are no more than 0 network connections for 500ms
- networkidle2: Fires when there are no more than 2 network connections for 500ms
The choice of wait condition affects both reliability and performance of automation scripts.
Usage
Use this principle after creating a page and before performing any page interaction or data extraction. Choose the appropriate wait condition based on the page's loading behavior: use networkidle0 for pages that load all content synchronously, domcontentloaded for fast initial checks, and load as the default safe choice.
Theoretical Basis
Navigation follows the browser's standard loading pipeline:
# Navigation lifecycle
1. URL requested via goto(url, options)
2. Browser resolves DNS and initiates connection
3. Main resource (HTML) is fetched
4. HTML parser begins constructing DOM
5. Sub-resources discovered and fetched (CSS, JS, images)
6. DOMContentLoaded event fires (DOM complete)
7. Load event fires (all resources complete)
8. Network idle detection (no pending requests)
9. Navigation promise resolves with HTTPResponse
The waitUntil parameter controls which stage in this pipeline marks the navigation as complete.