Implementation:Puppeteer Puppeteer Target
| Sources | packages/puppeteer-core/src/api/Target.ts |
|---|---|
| Domains | CDP Debugging, Target Management, Browser Introspection |
| Last Updated | 2026-02-12 |
Overview
Target is the abstract base class that represents a Chrome DevTools Protocol (CDP) target, which is any debuggable entity such as a page, frame, service worker, or the browser itself.
Description
The Target class models the CDP concept of a debugging target. In the Chrome DevTools Protocol, a target is something that can be debugged -- this includes pages, background pages, service workers, shared workers, webviews, and the browser itself. The TargetType enum, also exported from this module, defines these categories: PAGE, BACKGROUND_PAGE, SERVICE_WORKER, SHARED_WORKER, BROWSER, WEBVIEW, OTHER, and an internal TAB type.
The class provides methods to access the associated Page or WebWorker depending on the target type. The page() method returns a Page for targets of type "page", "webview", or "background_page" (null otherwise), while worker() returns a WebWorker for "service_worker" or "shared_worker" targets (null otherwise). The asPage() method forcefully creates a Page for any target type, which is useful for handling targets of type "other" as pages.
Additional abstract methods provide the target's URL, the ability to create a CDP session attached to the target, the target's type classification, the parent browser and browser context references, and the opener target (null for top-level targets).
Usage
Target instances are not created directly by consumers. They are provided through browser and browser context events (targetcreated, targetchanged, targetdestroyed) and through methods such as Browser.targets() and BrowserContext.targets().
Code Reference
Source Location
packages/puppeteer-core/src/api/Target.ts
Signature
export enum TargetType {
PAGE = 'page',
BACKGROUND_PAGE = 'background_page',
SERVICE_WORKER = 'service_worker',
SHARED_WORKER = 'shared_worker',
BROWSER = 'browser',
WEBVIEW = 'webview',
OTHER = 'other',
TAB = 'tab', // internal
}
export abstract class Target {
async worker(): Promise<WebWorker | null>;
async page(): Promise<Page | null>;
abstract asPage(): Promise<Page>;
abstract url(): string;
abstract createCDPSession(): Promise<CDPSession>;
abstract type(): TargetType;
abstract browser(): Browser;
abstract browserContext(): BrowserContext;
abstract opener(): Target | undefined;
}
Import
import type {Target, TargetType} from 'puppeteer-core/src/api/Target.js';
I/O Contract
Inputs
| Parameter | Type | Description |
|---|---|---|
| (none) | — | Target methods take no parameters; all state is populated internally by the protocol layer |
Outputs
| Method | Return Type | Description |
|---|---|---|
| worker() | null> | The associated WebWorker, or null if target is not a worker type |
| page() | null> | The associated Page, or null if target is not a page type |
| asPage() | Promise<Page> |
Forces creation of a Page for any target type |
| url() | string |
The URL of this target |
| createCDPSession() | Promise<CDPSession> |
A new CDP session attached to this target |
| type() | TargetType |
The kind of target (page, worker, etc.) |
| browser() | Browser |
The parent browser |
| browserContext() | BrowserContext |
The parent browser context |
| opener() | undefined | The target that opened this target, or undefined for top-level |
Usage Examples
// List all targets in a browser
const targets = browser.targets();
for (const target of targets) {
console.log(`${target.type()}: ${target.url()}`);
}
// Wait for a new page target to appear
const newTarget = await browserContext.waitForTarget(
target => target.type() === 'page' && target.url() === 'https://example.com/',
);
const newPage = await newTarget.page();
// Create a CDP session for low-level protocol access
const target = page.target();
const cdpSession = await target.createCDPSession();
await cdpSession.send('Network.enable');
// Handle a target of type "other" as a page
const otherTarget = browser.targets().find(t => t.type() === 'other');
if (otherTarget) {
const page = await otherTarget.asPage();
console.log(await page.title());
}