Implementation:Microsoft Playwright CssParser

Overview

CssParser parses CSS selector strings into a structured AST (Abstract Syntax Tree), supporting standard CSS selectors extended with Playwright's custom pseudo-class functions.

Description

The parseCSS function tokenizes and parses CSS selector strings into a structured representation consisting of:

• CSSComplexSelectorList -- a list of complex selectors (comma-separated)
• CSSComplexSelector -- a sequence of simple selectors with combinators (descendant, child, adjacent, general sibling)
• CSSSimpleSelector -- a single selector with optional CSS text and function calls
• CSSFunction -- named functions with arguments (supporting Playwright's custom engines)

The parser handles custom selector engine names (registered via customNames parameter) and returns both the parsed structure and a list of all selector engine names found.

The module also includes InvalidSelectorError for reporting parse failures.

Usage

Used by the selector parser to handle the CSS portion of Playwright selectors.

Code Reference

Source Location

packages/playwright-core/src/utils/isomorphic/cssParser.ts (267 lines)

Function Signatures

export class InvalidSelectorError extends Error {}
export function isInvalidSelectorError(error: Error): boolean;

export type CSSFunctionArgument = CSSComplexSelector | number | string;
export type CSSFunction = { name: string; args: CSSFunctionArgument[] };
export type CSSSimpleSelector = { css?: string; functions: CSSFunction[] };
export type CSSComplexSelector = { simples: { selector: CSSSimpleSelector; combinator: ClauseCombinator }[] };
export type CSSComplexSelectorList = CSSComplexSelector[];

export function parseCSS(selector: string, customNames: Set<string>): {
  selector: CSSComplexSelectorList;
  names: string[];
};

Import

import { parseCSS, InvalidSelectorError } from '../utils/isomorphic/cssParser';

I/O Contract

Inputs

• selector: string -- CSS selector string to parse
• customNames: Set<string> -- set of registered custom engine names

Outputs

• Parsed CSSComplexSelectorList AST
• Array of engine names found in the selector
• Throws InvalidSelectorError on parse failure

Related Pages

• Microsoft_Playwright_Server_Selectors -- Selector registry using CSS parser
• Microsoft_Playwright_FrameSelectors -- Frame-level selector resolution
• Microsoft_Playwright_LocatorParser -- Locator string parsing