Implementation:Puppeteer Puppeteer ElementHandle Type Tests

Property	Value
sources	test-d/ElementHandle.test-d.ts
domains	Type Safety, Type Testing, CSS Selector Type Inference
last_updated	2026-02-12 00:00 GMT

Overview

Description

The ElementHandle Type Tests module is a comprehensive compile-time type test suite that validates Puppeteer's TypeScript type inference for CSS selector strings on the ElementHandle class. It uses the tsd library (expectType, expectNotType) to assert that Puppeteer's advanced template literal type system correctly maps CSS selector strings to their corresponding DOM element types.

The test file validates type inference for four ElementHandle methods:

• $(selector) -- Single element query returning ElementHandle<T> | null
• $$(selector) -- Multi-element query returning Array<ElementHandle<T>>
• $eval(selector, fn) -- Evaluate function with typed element parameter
• $$eval(selector, fn) -- Evaluate function with typed element array parameter
• waitForSelector(selector) -- Wait for element with typed return

For each method, the tests cover multiple selector patterns:

• Known HTML elements -- 'a' maps to HTMLAnchorElement, 'div' maps to HTMLDivElement
• Selector modifiers -- IDs ('a#id'), classes ('a.class'), attributes ('a[attr=value]'), pseudo-classes ('a:pseudo-class'), functional pseudo-classes ('a:func(arg)')
• Compound selectors -- Descendant combinators ('div > a') where the rightmost element determines the type
• Custom elements -- 'some-custom' resolves to generic Element
• Non-element selectors -- '#id', '.class', '[attr=value]' resolve to generic Element

The tests also validate that $eval and $$eval correctly type the callback parameters and return values, including support for additional arguments passed through to the page function.

Usage

This file is executed at compile time by tsd during the Puppeteer CI pipeline. It does not produce runtime behavior but ensures that the TypeScript type definitions remain correct as the codebase evolves.

Code Reference

Source Location

test-d/ElementHandle.test-d.ts

Signature

// No runtime exports -- compile-time type assertions only
import type {ElementHandle} from 'puppeteer';
import {expectNotType, expectType} from 'tsd';

declare const handle: ElementHandle;

// Type assertions using expectType and expectNotType
expectType<ElementHandle<HTMLAnchorElement> | null>(await handle.$('a'));
expectNotType<ElementHandle<Element> | null>(await handle.$('a'));

Import

// This is a test file, not imported by other modules.
// It is run by tsd for compile-time type checking.
import type {ElementHandle} from 'puppeteer';
import {expectNotType, expectType} from 'tsd';

I/O Contract

Type Inference Rules Validated

Selector Pattern	Inferred Type	Example
Known HTML tag	Specific HTML element interface	'a' -> HTMLAnchorElement
Known tag with modifier	Same specific HTML element interface	'a#id' -> HTMLAnchorElement
Custom element tag	Generic Element	'some-custom' -> Element
Non-tag selector	Generic Element	'#id', '.class' -> Element
Compound selector	Rightmost element type	'div > a' -> HTMLAnchorElement
Compound with custom	Generic Element	'div > some-custom' -> Element

Methods Tested

Method	Return Type Pattern	Notes
$(selector)	null	Single element query
$$(selector)	Array<ElementHandle<T>>	Multi-element query
$eval(selector, fn, ...args)	Return type of fn	Callback receives typed element and extra args
$$eval(selector, fn, ...args)	Return type of fn	Callback receives typed element array and extra args
waitForSelector(selector)	null	Waits for element matching selector

Usage Examples

// These are compile-time type assertions, not runtime code.
// They ensure Puppeteer's type system correctly infers element types from selectors.

import type {ElementHandle} from 'puppeteer';
import {expectType, expectNotType} from 'tsd';

declare const handle: ElementHandle;

// Known tag 'a' infers HTMLAnchorElement
expectType<ElementHandle<HTMLAnchorElement> | null>(await handle.$('a'));
expectNotType<ElementHandle<Element> | null>(await handle.$('a'));

// Known tag 'div' infers HTMLDivElement
expectType<ElementHandle<HTMLDivElement> | null>(await handle.$('div'));

// Custom element falls back to generic Element
expectType<ElementHandle<Element> | null>(await handle.$('some-custom'));

// Compound selector: rightmost element determines type
expectType<ElementHandle<HTMLAnchorElement> | null>(await handle.$('div > a'));

// $eval correctly types the callback element parameter
expectType<void>(
  await handle.$eval('a', (element, int) => {
    expectType<HTMLAnchorElement>(element);
    expectType<number>(int);
  }, 1),
);

// $$eval correctly types the callback elements parameter
expectType<number>(
  await handle.$$eval('a', (elements, value) => {
    expectType<HTMLAnchorElement[]>(elements);
    return value;
  }, 1),
);

// waitForSelector with known tag
expectType<ElementHandle<HTMLAnchorElement> | null>(
  await handle.waitForSelector('a'),
);

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime