Implementation:Puppeteer Puppeteer Cdp Accessibility

Property	Value
sources	packages/puppeteer-core/src/cdp/Accessibility.ts
domains	Accessibility, CDP, Browser Automation
last_updated	2026-02-12 00:00 GMT

Overview

Description

The Accessibility class provides methods for inspecting the browser's accessibility tree via the Chrome DevTools Protocol (CDP). The accessibility tree is a representation of the page's structure used by assistive technologies such as screen readers and switch access devices.

Blink (Chrome's rendering engine) maintains an internal accessibility tree that is translated into platform-specific accessibility APIs. This module gives Puppeteer users direct access to that Blink Accessibility Tree. By default, the implementation filters out uninteresting nodes (those that most screen readers would ignore), exposing only the semantically meaningful nodes. This behavior can be overridden with the interestingOnly option.

The module consists of two main components:

• Accessibility -- The public-facing class that captures accessibility tree snapshots via the Accessibility.getFullAXTree CDP command, serializes the tree, and optionally populates iframe subtrees.
• AXNode -- An internal class that wraps individual Protocol.Accessibility.AXNode payloads, builds a parent-child tree structure, classifies nodes as controls/landmarks/leaf nodes, determines "interestingness," and serializes nodes into the public SerializedAXNode interface.

Usage

The Accessibility class is accessed via page.accessibility or frame.accessibility. The primary method is snapshot(), which returns a tree of SerializedAXNode objects representing the current state of the accessibility tree.

Code Reference

Source Location: packages/puppeteer-core/src/cdp/Accessibility.ts (784 lines)

Signature:

export class Accessibility {
  constructor(realm: Realm, frameId?: string);
  public async snapshot(options?: SnapshotOptions): Promise<SerializedAXNode | null>;
}

export interface SnapshotOptions {
  interestingOnly?: boolean;   // default: true
  includeIframes?: boolean;    // default: false
  root?: ElementHandle<Node>;
}

export interface SerializedAXNode {
  role: string;
  name?: string;
  value?: string | number;
  description?: string;
  children?: SerializedAXNode[];
  elementHandle(): Promise<ElementHandle | null>;
  // ... additional ARIA properties
}

Import:

import { Accessibility, type SerializedAXNode, type SnapshotOptions } from 'puppeteer-core/lib/cdp/Accessibility.js';

I/O Contract

Inputs:

Parameter	Type	Required	Description
options	SnapshotOptions	No	Configuration for the snapshot
options.interestingOnly	boolean	No	When true (default), prunes uninteresting nodes from the tree
options.includeIframes	boolean	No	When true, recursively fetches accessibility trees for iframes
options.root	ElementHandle<Node>	No	Root node to scope the accessibility tree; defaults to full page

Outputs:

Output	Type	Description
snapshot	null	The root node of the accessibility tree, or null if the tree is empty or the root element was not found

Usage Examples

// Dump the entire accessibility tree
const snapshot = await page.accessibility.snapshot();
console.log(snapshot);

// Get only the interesting nodes (default behavior)
const filteredSnapshot = await page.accessibility.snapshot({
  interestingOnly: true,
});

// Get the full unfiltered tree
const fullSnapshot = await page.accessibility.snapshot({
  interestingOnly: false,
});

// Scope the tree to a specific element
const elementHandle = await page.$('#main-content');
const scopedSnapshot = await page.accessibility.snapshot({
  root: elementHandle,
});

// Include iframe accessibility trees
const iframeSnapshot = await page.accessibility.snapshot({
  includeIframes: true,
});

// Find the focused node in the tree
const snapshot = await page.accessibility.snapshot();
function findFocusedNode(node) {
  if (node.focused) return node;
  for (const child of node.children || []) {
    const foundNode = findFocusedNode(child);
    if (foundNode) return foundNode;
  }
  return null;
}
const focusedNode = findFocusedNode(snapshot);
console.log(focusedNode && focusedNode.name);

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime