Implementation:Microsoft Playwright FrameSelectors

Overview

FrameSelectors resolves Playwright selectors within frame contexts, handling cross-frame selector chains, element querying, and injected script coordination.

Description

The FrameSelectors class is associated with each Frame and provides the selector resolution pipeline. It parses selectors using the selector parser, resolves frame-piercing selectors (selectors that span across iframes), and injects the selector engine into the page's execution context for DOM querying.

Key capabilities:

• Parse selectors with strict mode support from browser context options
• Query single elements or multiple elements matching a selector
• Resolve selectors across frame boundaries using splitSelectorByFrame
• Coordinate with the injected script for in-page evaluation

Usage

Accessed via frame.selectors internally. Not directly used by end users.

Code Reference

Source Location

packages/playwright-core/src/server/frameSelectors.ts (193 lines)

Class Signature

export class FrameSelectors {
  readonly frame: Frame;
  constructor(frame: Frame)
  async query(selector: string, options?: StrictOptions & { mainWorld?: boolean }, scope?: ElementHandle): Promise<ElementHandle<Element> | null>
  async queryAll(selector: string): Promise<ElementHandle<Element>[]>
  async resolveInjectedForSelector(selector: string, options?: StrictOptions, scope?: ElementHandle): Promise<ResolvedSelector | null>
}

Types

export type SelectorInfo = {
  parsed: ParsedSelector;
  world: types.World;
  strict: boolean;
};

export type SelectorInFrame = {
  frame: Frame;
  info: SelectorInfo;
  scope?: ElementHandle;
};

Import

import { FrameSelectors } from './server/frameSelectors';

I/O Contract

Inputs

• selector: string -- Playwright selector string
• options: StrictOptions -- optional strict mode settings
• scope: ElementHandle -- optional scope element for relative queries

Outputs

• ElementHandle or null for single queries
• Array of ElementHandle for queryAll
• ResolvedSelector containing injected script handle and frame info

Related Pages

• Microsoft_Playwright_Server_Selectors -- Selector engine registry
• Microsoft_Playwright_CssParser -- CSS selector parsing