Implementation:Microsoft Playwright Frames

Knowledge Sources	Microsoft_Playwright
Domains	Frame Management, Navigation
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for managing page frames and navigation on the server side provided by the Playwright library.

Description

The `frames.ts` module is one of the largest and most critical modules in Playwright, containing the `FrameManager` and `Frame` classes. The `FrameManager` class tracks all frames within a page, handles frame attachment/detachment, navigation lifecycle events, and execution context creation/destruction. The `Frame` class (extending `SdkObject`) represents an individual frame and provides the core automation API: navigation (`goto`, `waitForNavigation`, `waitForURL`), element selection and interaction (`click`, `fill`, `type`, `selectOption`), JavaScript evaluation (`evaluate`, `evaluateHandle`), waiting for selectors/functions/load states, content manipulation (`setContent`, `content`), and file upload handling. It uses `FrameSelectors` for element resolution and maintains execution context promises for both the main world and utility world.

Usage

Use this module for all frame-level operations in the Playwright server. It is the central abstraction for navigation, element interaction, and JavaScript evaluation across all browser engines.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/server/frames.ts

Signature

export class FrameManager {
  readonly _page: Page;
  private _frames: Map<string, Frame>;
  private _mainFrame: Frame;

  constructor(page: Page);
  mainFrame(): Frame;
  frames(): Frame[];
  frame(options: { frameId?: string, name?: string, url?: RegExp | string }): Frame | null;
  frameAttached(frameId: string, parentFrameId: string | null): Frame;
  frameDetached(frameId: string): void;
}

export class Frame extends SdkObject<FrameEventMap> {
  readonly _page: Page;
  readonly _id: string;

  async goto(progress: Progress, url: string, options: types.GotoOptions): Promise<network.Response | null>;
  async waitForNavigation(progress: Progress, options: types.NavigateOptions): Promise<network.Response | null>;
  async click(progress: Progress, selector: string, options: types.MouseClickOptions): Promise<void>;
  async fill(progress: Progress, selector: string, value: string, options: types.NavigatingActionWaitOptions): Promise<void>;
  async evaluate<R>(pageFunction: string | Function, arg?: any): Promise<R>;
  async waitForSelector(progress: Progress, selector: string, options: types.WaitForElementOptions): Promise<dom.ElementHandle | null>;
  async setContent(progress: Progress, html: string, options: types.NavigateOptions): Promise<void>;
  async content(): Promise<string>;
}

Import

import { FrameManager, Frame } from '../server/frames';
import type { GotoResult, NavigationEvent } from '../server/frames';

I/O Contract

Inputs

Name	Type	Required	Description
page	Page	Yes	The page that owns this frame manager
progress	Progress	Yes	Progress tracker for timeout and cancellation
url	string	Yes	URL for navigation
selector	string	Yes	Playwright selector for element queries
options	various	No	Action-specific options (timeout, waitUntil, etc.)

Outputs

Name	Type	Description
Frame	Frame	Frame instance for interaction
Response	network.Response or null	Navigation response
ElementHandle	dom.ElementHandle or null	Element handle from selector queries
content	string	HTML content of the frame
evaluation result	any	Result of JavaScript evaluation

Usage Examples

// FrameManager usage within Page
const frameManager = new FrameManager(page);
const mainFrame = frameManager.mainFrame();

// Frame navigation
const response = await mainFrame.goto(progress, 'https://example.com', { waitUntil: 'load' });

// Element interaction
await mainFrame.click(progress, 'button#submit', { timeout: 5000 });
await mainFrame.fill(progress, 'input[name="email"]', 'test@example.com', {});

// JavaScript evaluation
const title = await mainFrame.evaluate(() => document.title);

// Wait for selector
const handle = await mainFrame.waitForSelector(progress, '.loaded', { state: 'visible' });

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment