Implementation:Puppeteer Puppeteer Injected Util

Property	Value
sources	packages/puppeteer-core/src/injected/util.ts
domains	Injected Scripts, Shadow DOM, Visibility
last_updated	2026-02-12 00:00 GMT

Overview

Description

The Injected Util module provides low-level utility functions that run inside the browser page context. It contains three primary exports:

• checkVisibility(node, visible) -- Determines whether a node meets a visibility condition. When visible is undefined, returns the node itself (truthy). When visible is true or false, checks the element's computed visibility style (excluding hidden and collapse) and bounding box dimensions, returning the node only if its visibility matches the requested state.
• pierce(root) -- A generator that yields the shadow root of the given node if one exists, otherwise yields the node itself. Used for single-level shadow DOM piercing.
• pierceAll(root) -- A generator that recursively yields the node (or its shadow root) and then walks the entire subtree, yielding every shadow root encountered. Used for deep shadow DOM piercing across all levels.

Usage

These utilities are consumed by the P-selector query engine (PQuerySelector.ts) to implement the >>>> (child) and >>> (descendent) deep combinators. The checkVisibility function is used by wait-for-selector logic to filter elements based on visibility state.

Code Reference

Source Location

packages/puppeteer-core/src/injected/util.ts (72 lines)

Signature

export const checkVisibility: (node: Node | null, visible?: boolean) => Node | boolean;

export function* pierce(root: Node): IterableIterator<Node | ShadowRoot>;

export function* pierceAll(root: Node): IterableIterator<Node | ShadowRoot>;

Import

import { checkVisibility, pierce, pierceAll } from '../injected/util.js';

I/O Contract

checkVisibility

Direction	Name	Type	Description
Input	node	null	The DOM node to check
Input	visible	undefined	If undefined, returns the node as-is; if true/false, checks visibility
Output	result	boolean	The node if the visibility matches, false otherwise; returns true if node is null and visible is false

pierce

Direction	Name	Type	Description
Input	root	Node	The node to pierce
Output	result	ShadowRoot>	Yields the shadow root if present, otherwise the node itself

pierceAll

Direction	Name	Type	Description
Input	root	Node	The root node to begin deep traversal from
Output	result	ShadowRoot>	Yields the root (or its shadow root) and all nested shadow roots in the subtree

Usage Examples

import { checkVisibility, pierce, pierceAll } from '../injected/util.js';

// Check if a node is visible
const element = document.querySelector('.my-element');
const isVisible = checkVisibility(element, true);
if (isVisible) {
  console.log('Element is visible');
}

// Check if a node is hidden
const isHidden = checkVisibility(element, false);

// Pierce one level of shadow DOM
for (const node of pierce(element!)) {
  console.log('Pierced to:', node);
}

// Deep pierce all shadow roots in a subtree
for (const node of pierceAll(document.body)) {
  console.log('Found root or shadow root:', node);
}

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime