0
# Puppeteer
1

2
Puppeteer is a comprehensive browser automation library that provides a high-level JavaScript API for controlling Chrome and Firefox browsers programmatically via the DevTools Protocol and WebDriver BiDi. It enables developers to automate web interactions, perform web scraping, generate PDFs and screenshots, run performance tests, and create end-to-end testing solutions.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import puppeteer, { Browser, Page, ElementHandle } from "puppeteer";
15
```
16

17
For CommonJS:
18

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

24
## Basic Usage
25

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

29
// Launch browser and create page
30
const browser = await puppeteer.launch();
31
const page = await browser.newPage();
32

33
// Navigate and interact
34
await page.goto("https://example.com");
35
await page.type("#search", "query");
36
await page.click("button[type=submit]");
37

38
// Take screenshot
39
await page.screenshot({ path: "example.png" });
40

41
// Extract data
42
const title = await page.title();
43
const links = await page.$$eval("a", (anchors) => 
44
  anchors.map((a) => ({ text: a.textContent, href: a.href }))
45
);
46

47
await browser.close();
48
```
49

50
## Architecture
51

52
Puppeteer is built around several key components:
53

54
- **PuppeteerNode**: Main entry point for launching and connecting to browsers
55
- **Browser**: Represents a browser instance that can manage multiple contexts and pages
56
- **BrowserContext**: Isolated browser environment (incognito-like) for managing related pages
57
- **Page**: Individual browser tab/window with navigation, interaction, and evaluation capabilities
58
- **Frame**: Represents frames within pages, including main frame and iframes
59
- **ElementHandle**: Handle to DOM elements for direct interaction and property access
60
- **JSHandle**: Handle to JavaScript objects in the browser context
61
- **Network Classes**: HTTPRequest and HTTPResponse for network monitoring and interception
62
- **Input Classes**: Keyboard, Mouse, and Touchscreen for simulating user interactions
63
- **Locators**: Modern element selection with automatic waiting and retry logic
64

65
## Capabilities
66

67
### Browser Management
68

69
Core browser lifecycle operations including launching browsers, creating contexts, and managing browser-level settings.
70

71
```typescript { .api }
72
function launch(options?: LaunchOptions): Promise<Browser>;
73
function connect(options: ConnectOptions): Promise<Browser>;
74
function defaultArgs(options?: LaunchOptions): string[];
75
function executablePath(): string;
76
```
77

78
[Browser Management](./browser-management.md)
79

80
### Page Navigation & Interaction
81

82
Page-level operations for navigation, content manipulation, element interaction, and JavaScript execution.
83

84
```typescript { .api }
85
class Page {
86
  goto(url: string, options?: GoToOptions): Promise<HTTPResponse | null>;
87
  click(selector: string, options?: ClickOptions): Promise<void>;
88
  type(selector: string, text: string, options?: TypeOptions): Promise<void>;
89
  $(selector: string): Promise<ElementHandle | null>;
90
  $$(selector: string): Promise<ElementHandle[]>;
91
  evaluate(pageFunction: Function, ...args: any[]): Promise<any>;
92
}
93
```
94

95
[Page Navigation & Interaction](./page-interaction.md)
96

97
### Element Handling
98

99
Direct element manipulation through ElementHandle for precise control over DOM elements.
100

101
```typescript { .api }
102
class ElementHandle {
103
  click(options?: ClickOptions): Promise<void>;
104
  type(text: string, options?: TypeOptions): Promise<void>;
105
  $(selector: string): Promise<ElementHandle | null>;
106
  boundingBox(): Promise<BoundingBox | null>;
107
  screenshot(options?: ScreenshotOptions): Promise<Uint8Array>;
108
}
109
```
110

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

113
### Locators & Waiting
114

115
Modern element selection with automatic waiting, retries, and fluent interface for reliable element interactions.
116

117
```typescript { .api }
118
class Locator<T> {
119
  click(options?: LocatorClickOptions): Promise<void>;
120
  fill(value: string, options?: ActionOptions): Promise<void>;
121
  waitHandle(options?: ActionOptions): Promise<HandleFor<T>>;
122
  filter<U extends T>(predicate: Predicate<T, U>): Locator<U>;
123
}
124
```
125

126
[Locators & Waiting](./locators-waiting.md)
127

128
### Network Control
129

130
Request and response interception, network monitoring, and offline mode simulation.
131

132
```typescript { .api }
133
class HTTPRequest {
134
  url(): string;
135
  method(): string;
136
  headers(): Record<string, string>;
137
  abort(errorCode?: ErrorCode): Promise<void>;
138
  continue(overrides?: ContinueRequestOverrides): Promise<void>;
139
  respond(response: Partial<ResponseForRequest>): Promise<void>;
140
}
141

142
class HTTPResponse {
143
  status(): number;
144
  headers(): Record<string, string>;
145
  text(): Promise<string>;
146
  json(): Promise<any>;
147
  buffer(): Promise<Buffer>;
148
}
149
```
150

151
[Network Control](./network-control.md)
152

153
### Input & Interaction
154

155
Keyboard, mouse, and touch input simulation for comprehensive user interaction automation.
156

157
```typescript { .api }
158
class Keyboard {
159
  type(text: string, options?: {delay?: number}): Promise<void>;
160
  press(key: KeyInput, options?: PressOptions): Promise<void>;
161
  down(key: KeyInput): Promise<void>;
162
  up(key: KeyInput): Promise<void>;
163
}
164

165
class Mouse {
166
  click(x: number, y: number, options?: MouseClickOptions): Promise<void>;
167
  move(x: number, y: number, options?: {steps?: number}): Promise<void>;
168
  dragAndDrop(start: Point, target: Point): Promise<void>;
169
}
170
```
171

172
[Input & Interaction](./input-interaction.md)
173

174
### Media Generation
175

176
Screenshot capture and PDF generation with extensive customization options.
177

178
```typescript { .api }
179
interface ScreenshotOptions {
180
  path?: string;
181
  type?: "png" | "jpeg" | "webp";
182
  quality?: number;
183
  fullPage?: boolean;
184
  clip?: {x: number; y: number; width: number; height: number};
185
}
186

187
interface PDFOptions {
188
  path?: string;
189
  scale?: number;
190
  displayHeaderFooter?: boolean;
191
  headerTemplate?: string;
192
  footerTemplate?: string;
193
  printBackground?: boolean;
194
  landscape?: boolean;
195
  pageRanges?: string;
196
  format?: string;
197
  margin?: {top?: string; right?: string; bottom?: string; left?: string};
198
}
199
```
200

201
[Media Generation](./media-generation.md)
202

203
### Device Emulation
204

205
Mobile device emulation, viewport management, and browser environment simulation.
206

207
```typescript { .api }
208
interface Device {
209
  name: string;
210
  userAgent: string;
211
  viewport: Viewport;
212
}
213

214
interface Viewport {
215
  width: number;
216
  height: number;
217
  deviceScaleFactor?: number;
218
  isMobile?: boolean;
219
  hasTouch?: boolean;
220
  isLandscape?: boolean;
221
}
222
```
223

224
[Device Emulation](./device-emulation.md)
225

226
### Performance & Debugging
227

228
Performance tracing, code coverage collection, and accessibility tree inspection.
229

230
```typescript { .api }
231
class Coverage {
232
  startJSCoverage(options?: JSCoverageOptions): Promise<void>;
233
  stopJSCoverage(): Promise<JSCoverageEntry[]>;
234
  startCSSCoverage(options?: CSSCoverageOptions): Promise<void>;
235
  stopCSSCoverage(): Promise<CSSCoverageEntry[]>;
236
}
237

238
class Tracing {
239
  start(options?: TracingOptions): Promise<void>;
240
  stop(): Promise<Uint8Array>;
241
}
242
```
243

244
[Performance & Debugging](./performance-debugging.md)
245

246
## Core Types
247

248
```typescript { .api }
249
interface LaunchOptions {
250
  headless?: boolean | "new" | "shell";
251
  executablePath?: string;
252
  args?: string[];
253
  ignoreDefaultArgs?: boolean | string[];
254
  handleSIGINT?: boolean;
255
  handleSIGTERM?: boolean;
256
  handleSIGHUP?: boolean;
257
  timeout?: number;
258
  dumpio?: boolean;
259
  env?: Record<string, string | undefined>;
260
  devtools?: boolean;
261
  slowMo?: number;
262
  defaultViewport?: Viewport | null;
263
  ignoreHTTPSErrors?: boolean;
264
}
265

266
interface ConnectOptions {
267
  browserWSEndpoint?: string;
268
  browserURL?: string;
269
  ignoreHTTPSErrors?: boolean;
270
  defaultViewport?: Viewport | null;
271
  slowMo?: number;
272
  targetFilter?: (target: Target) => boolean;
273
}
274

275
interface GoToOptions {
276
  timeout?: number;
277
  waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2" | Array<"load" | "domcontentloaded" | "networkidle0" | "networkidle2">;
278
  referer?: string;
279
}
280

281
interface ClickOptions {
282
  button?: "left" | "right" | "middle";
283
  clickCount?: number;
284
  delay?: number;
285
  offset?: {x: number; y: number};
286
}
287

288
type KeyInput = "F1" | "F2" | "F3" | "F4" | "F5" | "F6" | "F7" | "F8" | "F9" | "F10" | "F11" | "F12" | "Digit0" | "Digit1" | "Digit2" | "Digit3" | "Digit4" | "Digit5" | "Digit6" | "Digit7" | "Digit8" | "Digit9" | "KeyA" | "KeyB" | "KeyC" | "KeyD" | "KeyE" | "KeyF" | "KeyG" | "KeyH" | "KeyI" | "KeyJ" | "KeyK" | "KeyL" | "KeyM" | "KeyN" | "KeyO" | "KeyP" | "KeyQ" | "KeyR" | "KeyS" | "KeyT" | "KeyU" | "KeyV" | "KeyW" | "KeyX" | "KeyY" | "KeyZ" | "Comma" | "Period" | "Semicolon" | "Quote" | "BracketLeft" | "BracketRight" | "Backquote" | "Backslash" | "Minus" | "Equal" | "IntlBackslash" | "IntlRo" | "IntlYen" | "ControlLeft" | "ControlRight" | "ShiftLeft" | "ShiftRight" | "AltLeft" | "AltRight" | "MetaLeft" | "MetaRight" | "ContextMenu" | "Escape" | "Tab" | "CapsLock" | "Space" | "PageUp" | "PageDown" | "End" | "Home" | "ArrowLeft" | "ArrowUp" | "ArrowRight" | "ArrowDown" | "PrintScreen" | "Insert" | "Delete" | "Backspace" | "Enter";
289

290
interface BoundingBox {
291
  x: number;
292
  y: number;
293
  width: number;
294
  height: number;
295
}
296

297
interface Point {
298
  x: number;
299
  y: number;
300
}
301

302
interface Cookie {
303
  name: string;
304
  value: string;
305
  domain: string;
306
  path: string;
307
  expires?: number;
308
  size?: number;
309
  httpOnly?: boolean;
310
  secure?: boolean;
311
  session?: boolean;
312
  sameSite?: "Strict" | "Lax" | "None";
313
}
314
```