Implementation:Puppeteer Puppeteer Debug
| Property | Value |
|---|---|
| sources | packages/puppeteer-core/src/common/Debug.ts |
| domains | Debugging, Logging, Diagnostics |
| last_updated | 2026-02-12 00:00 GMT |
Overview
Description
Debug is an internal module that provides a cross-environment debug logging function for Puppeteer. It exports a debug factory function that creates a prefixed logger, an importDebug function for lazy-loading the Node.js debug npm package, and helper functions setLogCapture and getCapturedLogs for capturing log output during testing.
In a Node.js environment, the debug function delegates to the debug npm module, which is controlled via the DEBUG environment variable (e.g., DEBUG=* to log all channels, DEBUG=puppeteer:* to log all Puppeteer channels). In browser environments, it falls back to console.log, controlled by setting window.__PUPPETEER_DEBUG to a matching pattern string.
The log capture mechanism allows internal code to temporarily capture all debug log messages into an array, which is useful for error reporting and diagnostics.
Usage
This module is used extensively throughout Puppeteer's internals to provide configurable debug logging. The primary consumer is the debugError constant in util.ts, which creates a logger prefixed with 'puppeteer:error'.
Code Reference
Source Location
packages/puppeteer-core/src/common/Debug.ts
Signature
export async function importDebug(): Promise<typeof Debug>;
export const debug: (prefix: string) => ((...args: unknown[]) => void);
export function setLogCapture(value: boolean): void;
export function getCapturedLogs(): string[];
Import
import {debug, importDebug, setLogCapture, getCapturedLogs} from './Debug.js';
I/O Contract
| Parameter | Type | Description |
|---|---|---|
| prefix | string |
The prefix string prepended to each log message (used as the debug channel name) |
| Function | Return Type | Description |
|---|---|---|
debug(prefix) |
(...args: unknown[]) => void |
Returns a logging function scoped to the given prefix/channel |
importDebug() |
Promise<typeof Debug> |
Lazily imports and caches the Node.js debug module
|
setLogCapture(value) |
void |
Enables or disables log capture; resets the captured log array |
getCapturedLogs() |
string[] |
Returns the array of captured log strings |
Usage Examples
import {debug} from './Debug.js';
// Create a debug logger with a specific prefix
const log = debug('puppeteer:page');
// Log a message (in Node.js, controlled by DEBUG env variable)
log('new page created');
// Output when DEBUG=puppeteer:* : "puppeteer:page: new page created"
// In the browser, set the debug level on the window object
// window.__PUPPETEER_DEBUG = 'puppeteer:*';
// Use log capture for diagnostics
import {setLogCapture, getCapturedLogs} from './Debug.js';
setLogCapture(true);
log('captured message');
const logs = getCapturedLogs();
// logs contains: ['puppeteer:pagecaptured message']
setLogCapture(false);