Implementation:Puppeteer Puppeteer Frame Wait Methods

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

Overview

Concrete tools for waiting on dynamic page content using selector matching and custom predicates, provided by the puppeteer-core library.

Description

The Frame class provides two waiting methods:

waitForSelector(): Waits for a CSS selector to match an element in the DOM. Can wait for elements to appear, become visible, or be removed.
waitForFunction(): Waits for an arbitrary JavaScript function to return a truthy value, evaluated in the browser context.

Both methods use the WaitTask polling mechanism defined in packages/puppeteer-core/src/common/WaitTask.ts.

Usage

Use these methods between navigation and data extraction to synchronize with dynamic page content.

Code Reference

Source Location

Repository: puppeteer
waitForSelector: packages/puppeteer-core/src/api/Frame.ts (lines 735-744)
waitForFunction: packages/puppeteer-core/src/api/Frame.ts (lines 781-794)
WaitTask: packages/puppeteer-core/src/common/WaitTask.ts (lines 1-273)

Signature

abstract class Frame {
  async waitForSelector<Selector extends string>(
    selector: Selector,
    options?: WaitForSelectorOptions,
  ): Promise<ElementHandle<NodeFor<Selector>> | null>;

  async waitForFunction<
    Params extends unknown[],
    Func extends EvaluateFunc<Params>,
  >(
    pageFunction: Func | string,
    options?: FrameWaitForFunctionOptions,
    ...args: Params
  ): Promise<HandleFor<Awaited<ReturnType<Func>>>>;
}

Import

// Accessed through Page or Frame instance
const page = await browser.newPage();
await page.waitForSelector('.result');
await page.waitForFunction('document.title === "Ready"');

I/O Contract

Inputs (waitForSelector)

Name	Type	Required	Description
selector	string	Yes	CSS selector to wait for
options.visible	boolean	No	Wait for element to be visible (not hidden by CSS)
options.hidden	boolean	No	Wait for element to be hidden or removed
options.timeout	number	No	Maximum wait time in ms (default: 30000)

Inputs (waitForFunction)

Name	Type	Required	Description
pageFunction	Function or string	Yes	Predicate to evaluate in browser context
options.polling	'raf' or 'mutation' or number	No	Polling strategy (default: 'raf')
options.timeout	number	No	Maximum wait time in ms (default: 30000)
...args	unknown[]	No	Arguments to pass to the predicate function

Outputs

Name	Type	Description
waitForSelector return	Promise<ElementHandle or null>	Handle to the matched element, or null if hidden option used
waitForFunction return	Promise<JSHandle>	Handle to the function's return value

Usage Examples

Wait For Element To Appear

await page.goto('https://example.com');
const element = await page.waitForSelector('.search-results');
const text = await element.evaluate(el => el.textContent);

Wait For Element To Be Visible

await page.waitForSelector('.modal', {visible: true});

Wait For Custom Condition

// Wait until page title changes
await page.waitForFunction(
  'document.title.includes("Results")',
  {timeout: 10000}
);

Wait With Arguments

// Wait until element count exceeds threshold
await page.waitForFunction(
  (selector, minCount) => document.querySelectorAll(selector).length >= minCount,
  {},
  '.item',
  10
);

Related Pages

Implements Principle

Principle:Puppeteer_Puppeteer_Dynamic_Content_Waiting

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