0
# Puppeteer Core
1

2
Puppeteer Core is a Node.js library providing a high-level API to control headless Chrome and Firefox browsers over the DevTools Protocol (CDP) and WebDriver BiDi. It enables browser automation for testing, scraping, PDF generation, performance monitoring, and accessibility analysis without bundling Chrome.
3

4
## Package Information
5

6
- **Package Name**: puppeteer-core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install puppeteer-core`
10

11
## Core Imports
12

13
```typescript
14
import puppeteer, { Browser, Page, ElementHandle, Locator, Protocol, CDPSession } from "puppeteer-core";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const puppeteer = require("puppeteer-core");
21
const { Browser, Page, ElementHandle, Locator, Protocol, CDPSession } = puppeteer;
22
```
23

24
## Basic Usage
25

26
```typescript
27
import puppeteer from "puppeteer-core";
28

29
// Launch browser
30
const browser = await puppeteer.launch({
31
  executablePath: "/path/to/chrome", // Required for puppeteer-core
32
  headless: true
33
});
34

35
// Create page
36
const page = await browser.newPage();
37

38
// Navigate and interact
39
await page.goto("https://example.com");
40
await page.setViewport({ width: 1024, height: 768 });
41

42
// Take screenshot
43
await page.screenshot({ path: "example.png" });
44

45
// Close browser
46
await browser.close();
47
```
48

49
## Architecture
50

51
Puppeteer Core is built around several key components:
52

53
- **Browser Management**: Launch, connect, and control browser instances across Chrome and Firefox
54
- **Page Interaction**: Navigate pages, interact with elements, handle JavaScript execution
55
- **Protocol Support**: Dual implementation supporting both CDP (Chrome DevTools Protocol) and WebDriver BiDi
56
- **Input Simulation**: Keyboard, mouse, and touchscreen input with realistic timing
57
- **Network Control**: Request interception, response mocking, and traffic monitoring
58
- **Element Location**: Advanced locator system with multiple query strategies
59
- **Event Handling**: Comprehensive event system for browser, page, and element events
60

61
## Capabilities
62

63
### Browser Management
64

65
Core browser lifecycle management including launching new browser instances, connecting to existing ones, and managing browser contexts for isolation.
66

67
```typescript { .api }
68
function launch(options?: LaunchOptions): Promise<Browser>;
69
function connect(options: ConnectOptions): Promise<Browser>;
70
function defaultArgs(options?: LaunchOptions): string[];
71
function executablePath(): string;
72
```
73

74
[Browser Management](./browser-management.md)
75

76
### Page Navigation and Interaction
77

78
Complete page automation including navigation, element interaction, JavaScript execution, and content extraction.
79

80
```typescript { .api }
81
interface Page extends EventEmitter {
82
  goto(url: string, options?: GoToOptions): Promise<HTTPResponse | null>;
83
  setViewport(viewport: Viewport): Promise<void>;
84
  screenshot(options?: ScreenshotOptions): Promise<Buffer>;
85
  pdf(options?: PDFOptions): Promise<Buffer>;
86
  evaluate<T>(pageFunction: Function, ...args: any[]): Promise<T>;
87
  waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise<ElementHandle | null>;
88
  click(selector: string, options?: ClickOptions): Promise<void>;
89
  type(selector: string, text: string, options?: TypeOptions): Promise<void>;
90
}
91
```
92

93
[Page Navigation and Interaction](./page-interaction.md)
94

95
### Element Handling
96

97
Advanced element selection, interaction, and manipulation with comprehensive locator strategies and event handling.
98

99
```typescript { .api }
100
interface ElementHandle extends JSHandle {
101
  click(options?: ClickOptions): Promise<void>;
102
  type(text: string, options?: TypeOptions): Promise<void>;
103
  focus(): Promise<void>;
104
  hover(): Promise<void>;
105
  select(...values: string[]): Promise<string[]>;
106
  uploadFile(...filePaths: string[]): Promise<void>;
107
  boundingBox(): Promise<BoundingBox | null>;
108
  screenshot(options?: ScreenshotOptions): Promise<Buffer>;
109
}
110
```
111

112
[Element Handling](./element-handling.md)
113

114
### Input Simulation
115

116
Realistic keyboard, mouse, and touchscreen input simulation with timing controls and platform-specific key mappings.
117

118
```typescript { .api }
119
interface Keyboard {
120
  down(key: string, options?: KeyDownOptions): Promise<void>;
121
  up(key: string): Promise<void>;
122
  press(key: string, options?: PressOptions): Promise<void>;
123
  type(text: string, options?: TypeOptions): Promise<void>;
124
  sendCharacter(char: string): Promise<void>;
125
}
126

127
interface Mouse {
128
  move(x: number, y: number, options?: MouseMoveOptions): Promise<void>;
129
  click(x: number, y: number, options?: ClickOptions): Promise<void>;
130
  down(options?: MouseDownOptions): Promise<void>;
131
  up(options?: MouseUpOptions): Promise<void>;
132
  wheel(options?: MouseWheelOptions): Promise<void>;
133
}
134
```
135

136
[Input Simulation](./input-simulation.md)
137

138
### Network Management
139

140
Request interception, response mocking, and comprehensive network monitoring for testing and debugging.
141

142
```typescript { .api }
143
interface HTTPRequest {
144
  url(): string;
145
  method(): string;
146
  headers(): Record<string, string>;
147
  postData(): string | undefined;
148
  response(): HTTPResponse | null;
149
  abort(errorCode?: string): Promise<void>;
150
  continue(overrides?: ContinueRequestOverrides): Promise<void>;
151
  respond(response: ResponseForRequest): Promise<void>;
152
}
153

154
interface HTTPResponse {
155
  ok(): boolean;
156
  status(): number;
157
  statusText(): string;
158
  headers(): Record<string, string>;
159
  url(): string;
160
  text(): Promise<string>;
161
  json(): Promise<any>;
162
  buffer(): Promise<Buffer>;
163
}
164
```
165

166
[Network Management](./network-management.md)
167

168
### Locators and Selectors
169

170
Advanced element location strategies including CSS selectors, XPath, text content, custom query handlers, and the modern Locator API.
171

172
```typescript { .api }
173
interface Locator<T> {
174
  click(options?: LocatorClickOptions): Promise<void>;
175
  fill(value: string, options?: LocatorFillOptions): Promise<void>;
176
  hover(options?: LocatorHoverOptions): Promise<void>;
177
  scroll(options?: LocatorScrollOptions): Promise<void>;
178
  wait(options?: LocatorWaitOptions): Promise<T>;
179
  waitFor(options?: LocatorWaitOptions): Promise<void>;
180
  map<U>(mapper: (value: T) => Promise<U>): Locator<U>;
181
  filter<U extends T>(predicate: (value: T) => Promise<boolean>): Locator<U>;
182
}
183
```
184

185
[Locators and Selectors](./locators-selectors.md)
186

187
### Browser Contexts
188

189
Isolated browser contexts for managing sessions, cookies, permissions, and parallel test execution.
190

191
```typescript { .api }
192
interface BrowserContext extends EventEmitter {
193
  newPage(): Promise<Page>;
194
  pages(): Page[];
195
  cookies(...urls: string[]): Promise<Cookie[]>;
196
  setCookie(...cookies: CookieParam[]): Promise<void>;
197
  clearPermissionOverrides(): Promise<void>;
198
  overridePermissions(origin: string, permissions: Permission[]): Promise<void>;
199
  setGeolocation(options: GeolocationOptions): Promise<void>;
200
  close(): Promise<void>;
201
}
202
```
203

204
[Browser Contexts](./browser-contexts.md)
205

206
## Core Types
207

208
```typescript { .api }
209
interface LaunchOptions {
210
  executablePath?: string;
211
  headless?: boolean | "new";
212
  args?: string[];
213
  ignoreDefaultArgs?: boolean | string[];
214
  handleSIGINT?: boolean;
215
  handleSIGTERM?: boolean;
216
  handleSIGHUP?: boolean;
217
  timeout?: number;
218
  dumpio?: boolean;
219
  userDataDir?: string;
220
  env?: Record<string, string | undefined>;
221
  devtools?: boolean;
222
  pipe?: boolean;
223
  slowMo?: number;
224
  defaultViewport?: Viewport | null;
225
  ignoreHTTPSErrors?: boolean;
226
}
227

228
interface ConnectOptions {
229
  browserWSEndpoint?: string;
230
  browserURL?: string;
231
  ignoreHTTPSErrors?: boolean;
232
  defaultViewport?: Viewport | null;
233
  slowMo?: number;
234
  targetFilter?: (target: Target) => boolean;
235
  headers?: Record<string, string>;
236
}
237

238
interface Viewport {
239
  width: number;
240
  height: number;
241
  deviceScaleFactor?: number;
242
  isMobile?: boolean;
243
  hasTouch?: boolean;
244
  isLandscape?: boolean;
245
}
246

247
interface Cookie {
248
  name: string;
249
  value: string;
250
  domain?: string;
251
  path?: string;
252
  expires?: number;
253
  size?: number;
254
  httpOnly?: boolean;
255
  secure?: boolean;
256
  session?: boolean;
257
  sameSite?: "Strict" | "Lax" | "None";
258
  priority?: "Low" | "Medium" | "High";
259
  sameParty?: boolean;
260
  sourceScheme?: "Unset" | "NonSecure" | "Secure";
261
  partitionKey?: string;
262
}
263

264
type Protocol = "cdp" | "webDriverBiDi";
265

266
interface Target {
267
  createCDPSession(): Promise<CDPSession>;
268
  page(): Promise<Page | null>;
269
  url(): string;
270
  type(): "page" | "background_page" | "service_worker" | "shared_worker" | "other" | "browser" | "webview";
271
  browser(): Browser;
272
  browserContext(): BrowserContext;
273
  opener(): Target | undefined;
274
}
275

276
interface CDPSession extends EventEmitter {
277
  send<T = any>(method: string, ...paramArgs: any[]): Promise<T>;
278
  connection(): Connection | undefined;
279
  detach(): Promise<void>;
280
  id(): string;
281
}
282

283
interface Connection extends EventEmitter {
284
  url(): string;
285
  send<T = any>(method: string, ...paramArgs: any[]): Promise<T>;
286
  createSession(targetInfo: Target): Promise<CDPSession>;
287
  dispose(): void;
288
}
289

290
interface ExecutionContext {
291
  evaluate<T>(pageFunction: Function, ...args: any[]): Promise<T>;
292
  evaluateHandle<T>(pageFunction: Function, ...args: any[]): Promise<JSHandle<T>>;
293
  frame(): Frame | null;
294
  queryObjects<T>(prototypeHandle: JSHandle<T>): Promise<HandleFor<T[]>>;
295
}
296

297
interface FileChooser {
298
  isMultiple(): boolean;
299
  accept(filePaths: string[]): Promise<void>;
300
  cancel(): Promise<void>;
301
}
302

303
type HandleFor<T> = T extends Node ? ElementHandle<T> : JSHandle<T>;
304
```
305

306
## Error Classes
307

308
```typescript { .api }
309
class PuppeteerError extends Error {
310
  constructor(message?: string, options?: ErrorOptions);
311
}
312

313
class TimeoutError extends PuppeteerError {
314
  constructor(message?: string, options?: ErrorOptions);
315
}
316

317
class TouchError extends PuppeteerError {
318
  constructor(message?: string, options?: ErrorOptions);
319
}
320

321
class ProtocolError extends PuppeteerError {
322
  constructor(message?: string, options?: ErrorOptions);
323
  code?: number;
324
  originalMessage: string;
325
}
326

327
class UnsupportedOperation extends PuppeteerError {
328
  constructor(message?: string, options?: ErrorOptions);
329
}
330

331
class TargetCloseError extends ProtocolError {
332
  constructor(message?: string, options?: ErrorOptions);
333
}
334

335
class ConnectionClosedError extends ProtocolError {
336
  constructor(message?: string, options?: ErrorOptions);
337
}
338
```
339

340
## Protocol Types
341

342
```typescript { .api }
343
namespace Protocol {
344
  // Chrome DevTools Protocol types (re-exported from devtools-protocol package)
345
  namespace Runtime {
346
    interface RemoteObject {
347
      type: "object" | "function" | "undefined" | "string" | "number" | "boolean" | "symbol" | "bigint";
348
      subtype?: "array" | "null" | "node" | "regexp" | "date" | "map" | "set" | "weakmap" | "weakset" | "iterator" | "generator" | "error" | "proxy" | "promise" | "typedarray" | "arraybuffer" | "dataview";
349
      className?: string;
350
      value?: any;
351
      unserializableValue?: string;
352
      description?: string;
353
      objectId?: string;
354
      preview?: ObjectPreview;
355
      customPreview?: CustomPreview;
356
    }
357

358
    interface ObjectPreview {
359
      type: "object" | "function" | "undefined" | "string" | "number" | "boolean" | "symbol" | "bigint";
360
      subtype?: "array" | "null" | "node" | "regexp" | "date" | "map" | "set" | "weakmap" | "weakset" | "iterator" | "generator" | "error" | "proxy" | "promise" | "typedarray" | "arraybuffer" | "dataview";
361
      description?: string;
362
      overflow: boolean;
363
      properties: PropertyPreview[];
364
      entries?: EntryPreview[];
365
    }
366

367
    interface PropertyPreview {
368
      name: string;
369
      type: "object" | "function" | "undefined" | "string" | "number" | "boolean" | "symbol" | "bigint" | "accessor";
370
      value?: string;
371
      valuePreview?: ObjectPreview;
372
      subtype?: "array" | "null" | "node" | "regexp" | "date" | "map" | "set" | "weakmap" | "weakset" | "iterator" | "generator" | "error" | "proxy" | "promise" | "typedarray" | "arraybuffer" | "dataview";
373
    }
374

375
    interface EntryPreview {
376
      key?: ObjectPreview;
377
      value: ObjectPreview;
378
    }
379

380
    interface CustomPreview {
381
      header: string;
382
      bodyGetterId?: string;
383
    }
384
  }
385
}
386
```