Implementation:Puppeteer Puppeteer PSelectorParser

Property	Value
sources	packages/puppeteer-core/src/common/PSelectorParser.ts
domains	Selector Parsing, Query Handling, CSS
last_updated	2026-02-12 00:00 GMT

Overview

Description

PSelectorParser is an internal module that parses Puppeteer's extended selector syntax ("P-selectors") into a structured representation. P-selectors extend standard CSS selectors with Puppeteer-specific pseudo-elements prefixed with ::-p- (e.g., ::-p-text, ::-p-aria) and extended combinator syntax (>>> for deep descendant, >>>> for deep child).

The module modifies the third-party parsel-js tokenizer to recognize:

• A nesting token for the & character.
• Extended combinator tokens for Puppeteer's deep descendant (>>>) and deep child (>>>>) combinators, in addition to standard CSS combinators.

The main exported function parsePSelectors tokenizes a selector string and produces a tuple containing:

1. selector -- A ComplexPSelectorList which is a structured AST of the parsed selector.
2. isPureCSS -- A boolean indicating whether the selector is pure CSS (no Puppeteer extensions), enabling optimized native CSS querying.
3. hasPseudoClasses -- A boolean indicating whether the selector contains any CSS pseudo-classes.
4. hasAria -- A boolean indicating whether the selector references the -p-aria pseudo-element.

The helper function unquote removes surrounding quotes and processes escape sequences in selector argument values.

Usage

This parser is used internally by Puppeteer's selector engine to determine how to route selector queries. Pure CSS selectors bypass the custom query pipeline entirely, while selectors containing ::-p- pseudo-elements are dispatched to the appropriate specialized handler (e.g., ARIAQueryHandler for ::-p-aria).

Code Reference

Source Location

packages/puppeteer-core/src/common/PSelectorParser.ts

Signature

export function parsePSelectors(
  selector: string,
): [
  selector: ComplexPSelectorList,
  isPureCSS: boolean,
  hasPseudoClasses: boolean,
  hasAria: boolean,
];

Import

import {parsePSelectors} from './PSelectorParser.js';

I/O Contract

Parameter	Type	Description
selector	string	A selector string which may contain standard CSS and/or Puppeteer-specific pseudo-elements

Return Index	Type	Description
0	ComplexPSelectorList	The parsed AST representing the selector structure
1	boolean	true if the selector is pure CSS with no Puppeteer extensions
2	boolean	true if the selector contains CSS pseudo-classes
3	boolean	true if the selector uses the ::-p-aria pseudo-element

Usage Examples

import {parsePSelectors} from './PSelectorParser.js';

// Pure CSS selector
const [ast1, isPureCSS1, hasPseudo1, hasAria1] = parsePSelectors('div.class > span');
// isPureCSS1 = true, hasPseudo1 = false, hasAria1 = false

// Puppeteer text pseudo-element
const [ast2, isPureCSS2, hasPseudo2, hasAria2] = parsePSelectors('div ::-p-text(Hello)');
// isPureCSS2 = false, hasPseudo2 = false, hasAria2 = false

// ARIA pseudo-element
const [ast3, isPureCSS3, hasPseudo3, hasAria3] = parsePSelectors('::-p-aria(Submit[role="button"])');
// isPureCSS3 = false, hasPseudo3 = false, hasAria3 = true

// CSS pseudo-class
const [ast4, isPureCSS4, hasPseudo4, hasAria4] = parsePSelectors('button:hover');
// isPureCSS4 = true, hasPseudo4 = true, hasAria4 = false

// Deep descendant combinator
const [ast5, isPureCSS5] = parsePSelectors('div >>> span');
// isPureCSS5 = false (uses Puppeteer-specific combinator)

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime