Implementation:Microsoft Playwright Dom

Knowledge Sources	Microsoft_Playwright
Domains	DOM Manipulation, Element Interaction
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for DOM element operations and interaction on the server side provided by the Playwright library.

Description

The `dom.ts` module provides the `FrameExecutionContext` class (extending `js.ExecutionContext` for frame-specific script execution) and the `ElementHandle` class for interacting with DOM elements. `ElementHandle` supports a comprehensive set of actions including clicking, double-clicking, tapping, hovering, filling input fields, selecting options, checking/unchecking checkboxes, setting input files, scrolling into view, taking element screenshots, and evaluating JavaScript on elements. The module implements Playwright's actionability framework with retry logic for visibility, stability, enabled state, and hit-target verification. The `NonRecoverableDOMError` class signals permanent failures that should not be retried. The `InjectedScript` interface provides the contract for in-page script execution.

Usage

Use this module when implementing element-level operations in the Playwright server. It provides the core abstraction for all DOM manipulation across all browser engines.

Code Reference

Source Location

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

Signature

export class FrameExecutionContext extends js.ExecutionContext {
  readonly frame: frames.Frame;
  readonly world: types.World | null;

  constructor(delegate: js.ExecutionContextDelegate, frame: frames.Frame, world: types.World | null);
  override adoptIfNeeded(handle: js.JSHandle): Promise<js.JSHandle> | null;
}

export class NonRecoverableDOMError extends Error {}

export class ElementHandle<T extends Node = Node> extends js.JSHandle<T> {
  readonly _page: Page;
  readonly _frame: frames.Frame;

  async click(progress: Progress, options: types.PointerActionOptions & types.NavigatingActionWaitOptions): Promise<void>;
  async fill(progress: Progress, value: string, options: types.NavigatingActionWaitOptions): Promise<void>;
  async selectOption(progress: Progress, elements: ElementHandle[], values: types.SelectOption[], options: types.NavigatingActionWaitOptions): Promise<string[]>;
  async setInputFiles(progress: Progress, items: InputFilesItems, options: types.NavigatingActionWaitOptions): Promise<void>;
  async screenshot(progress: Progress, options: ScreenshotOptions): Promise<Buffer>;
}

Import

import * as dom from '../server/dom';
import { FrameExecutionContext, ElementHandle } from '../server/dom';

I/O Contract

Inputs

Name	Type	Required	Description
delegate	js.ExecutionContextDelegate	Yes	Browser-specific execution context delegate
frame	frames.Frame	Yes	The frame this execution context belongs to
world	types.World or null	Yes	Execution world (main, utility, or content-script)
progress	Progress	Yes	Progress tracker for timeout and cancellation
options	various action options	Yes	Action-specific options (position, modifiers, timeout, etc.)

Outputs

Name	Type	Description
ElementHandle	ElementHandle	Handle to a DOM element for further interaction
screenshot	Buffer	Element screenshot data
selected values	string[]	Values selected in a select element
action result	PerformActionResult	Result of an action (done, error, or description of failure)

Usage Examples

// Get an element handle and interact with it
const context = new FrameExecutionContext(delegate, frame, 'main');
const handle = await context.evaluateHandle('document.querySelector("button")');

// Perform actions
await handle.click(progress, { position: { x: 10, y: 10 } });
await handle.fill(progress, 'Hello World', {});
const screenshot = await handle.screenshot(progress, { type: 'png' });

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment