Implementation:Puppeteer Puppeteer AriaQueryHandler
| Property | Value |
|---|---|
| sources | packages/puppeteer-core/src/common/AriaQueryHandler.ts |
| domains | Accessibility, Query Handling |
| last_updated | 2026-02-12 00:00 GMT |
Overview
Description
ARIAQueryHandler is an internal query handler class that enables selecting DOM elements based on their ARIA (Accessible Rich Internet Applications) attributes. It extends the base QueryHandler class to provide accessibility-tree-based element selection using the name and role ARIA properties. The handler parses a custom selector syntax that allows querying elements by their accessible name and role attribute, supporting patterns such as 'title[role="heading"]' or '[role="image"]'.
The module includes a private helper function parseARIASelector that processes the selector string using a regular expression to extract ARIA attribute values (name and role) from bracket notation. The parser enforces a maximum selector length of 10,000 characters to prevent abuse and validates that only known attributes (name and role) are used.
Usage
This handler is used internally by Puppeteer when selectors with the ARIA pseudo-element prefix (-p-aria) are encountered. It is not intended for direct external use. When a user writes a selector like ::-p-aria(Submit[role="button"]), the PSelectorParser routes the query to this handler, which then queries the accessibility tree via the browser's DevTools Protocol.
Code Reference
Source Location
packages/puppeteer-core/src/common/AriaQueryHandler.ts
Signature
interface ARIASelector {
name?: string;
role?: string;
}
export class ARIAQueryHandler extends QueryHandler {
static override querySelector: QuerySelector;
static override queryAll(
element: ElementHandle<Node>,
selector: string,
): AwaitableIterable<ElementHandle<Node>>;
static override queryOne(
element: ElementHandle<Node>,
selector: string,
): Promise<ElementHandle<Node> | null>;
}
Import
import {ARIAQueryHandler} from './AriaQueryHandler.js';
I/O Contract
| Parameter | Type | Description |
|---|---|---|
| element | ElementHandle<Node> |
The root element handle to start querying from |
| selector | string |
An ARIA selector string (e.g., 'Submit[role="button"]')
|
| Return Type | Description |
|---|---|
| null> | A handle to the first matching element, or null (for queryOne/querySelector) |
AwaitableIterable<ElementHandle<Node>> |
An async iterable of all matching element handles (for queryAll) |
Usage Examples
// Internal usage - typically invoked through Puppeteer's selector engine
// when using the ::-p-aria pseudo-element prefix
// Query for an element with accessible name "Submit" and role "button"
const button = await page.$('::-p-aria(Submit[role="button"])');
// Query for all elements with role "listitem"
const items = await page.$$('::-p-aria([role="listitem"])');
// Query by accessible name only
const heading = await page.$('::-p-aria(Welcome)');
// Query by role only
const images = await page.$$('::-p-aria([role="image"])');
// Query with empty name and specific role
const emptyNameButton = await page.$('::-p-aria([name=""][role="button"])');