Implementation:Microsoft Playwright SelectorParser

Knowledge Sources	Microsoft_Playwright
Domains	Selector Engine, Element Resolution
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for parsing Playwright selector strings into structured representations provided by the Playwright library.

Description

The `selectorParser.ts` module parses Playwright's selector syntax into a structured `ParsedSelector` representation. It handles the multi-engine selector format where selectors can be chained with `>>` (e.g., `css=div >> text="hello"`) and supports nested selectors for relational pseudo-classes (`has`, `has-not`, `and`, `or`, `chain`, `left-of`, `right-of`, `above`, `below`, `near`). The parser processes CSS selectors (delegating to the CSS parser), text selectors, internal selectors (role, testid, attr, label, etc.), and custom selector engines. It defines `customCSSNames` for Playwright's CSS extensions (`:visible`, `:text`, `:has-text`, `:nth-match`, etc.) and provides `stringifySelector` for converting parsed selectors back to strings. The `ParsedSelectorPart` type captures each segment with its engine name, body, and source text.

Usage

Use this module when processing Playwright selector strings anywhere in the codebase. It is the entry point for all selector resolution, consumed by `FrameSelectors` and the locator generators.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/utils/isomorphic/selectorParser.ts

Signature

export type ParsedSelectorPart = {
  name: string;
  body: string | CSSComplexSelectorList | NestedSelectorBody;
  source: string;
};

export type ParsedSelector = {
  parts: ParsedSelectorPart[];
  capture?: number;
};

export type NestedSelectorBody = { parsed: ParsedSelector, distance?: number };

export const customCSSNames: Set<string>;

export function parseSelector(selector: string): ParsedSelector;
export function stringifySelector(selector: ParsedSelector): string;
export { InvalidSelectorError, isInvalidSelectorError } from './cssParser';

Import

import { parseSelector, stringifySelector, ParsedSelector, ParsedSelectorPart } from '../utils/isomorphic/selectorParser';

I/O Contract

Inputs

Name	Type	Required	Description
selector	string	Yes	Playwright selector string (e.g., 'css=div >> text="hello"')

Outputs

Name	Type	Description
ParsedSelector	ParsedSelector	Structured selector with parts array and optional capture index
stringified	string	Selector string reconstructed from parsed representation

Usage Examples

import { parseSelector, stringifySelector } from 'playwright-core/lib/utils/isomorphic/selectorParser';

// Parse a chained selector
const parsed = parseSelector('css=div.container >> text="Hello World"');
// parsed.parts = [
//   { name: 'css', body: /* CSSComplexSelectorList */, source: 'div.container' },
//   { name: 'text', body: '"Hello World"', source: 'text="Hello World"' }
// ]

// Parse a role selector
const roleParsed = parseSelector('internal:role=button[name="Submit"i]');

// Roundtrip
const str = stringifySelector(parsed);

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment