0
# Puppeteer Compatibility
1

2
Compatibility layer that allows puppeteer-extra plugins to work seamlessly with Playwright by providing a shim layer that translates Playwright objects to Puppeteer-compatible interfaces. This enables reuse of the extensive puppeteer-extra plugin ecosystem.
3

4
## Capabilities
5

6
### Add Puppeteer Compatibility
7

8
Augment Playwright objects with compatibility methods for Puppeteer plugins.
9

10
```typescript { .api }
11
/**
12
 * Augment a Playwright object with compatibility with certain Puppeteer methods
13
 * @param object - Playwright Page, Frame, Browser, or null
14
 * @returns The same object enhanced with Puppeteer compatibility methods
15
 */
16
function addPuppeteerCompat<Input extends Page | Frame | Browser | null>(
17
  object: Input
18
): Input;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { addPuppeteerCompat } from "playwright-extra";
25
import { chromium } from "playwright";
26

27
// Manually add compatibility to Playwright objects
28
const browser = await chromium.launch();
29
const compatBrowser = addPuppeteerCompat(browser);
30

31
// Now browser has puppeteer-style methods
32
const userAgent = await compatBrowser.userAgent();
33
const pages = await compatBrowser.pages();
34
```
35

36
### Browser Compatibility Shim
37

38
Enhanced browser interface that provides Puppeteer-compatible methods for browser objects.
39

40
```typescript { .api }
41
interface PuppeteerBrowserShim {
42
  /** Indicates this is a compatibility shim */
43
  isCompatShim?: boolean;
44
  /** Indicates this is a Playwright object */
45
  isPlaywright?: boolean;
46
  /** Get all pages across all browser contexts */
47
  pages?: BrowserContext['pages'];
48
  /** Get the browser's user agent string */
49
  userAgent(): Promise<string>;
50
}
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
import { chromium } from "playwright-extra";
57

58
const browser = await chromium.launch();
59

60
// Puppeteer-style methods available on browser
61
const userAgent = await browser.userAgent();
62
console.log('User agent:', userAgent);
63

64
// Get all pages across contexts (Puppeteer style)
65
const pages = await browser.pages();
66
console.log('All pages:', pages.length);
67

68
// Check if object is shimmed
69
if (browser.isCompatShim) {
70
  console.log('Browser has Puppeteer compatibility');
71
}
72
```
73

74
### Page Compatibility Shim
75

76
Enhanced page and frame interface that provides Puppeteer-compatible methods.
77

78
```typescript { .api }
79
interface PuppeteerPageShim {
80
  /** Indicates this is a compatibility shim */
81
  isCompatShim?: boolean;
82
  /** Indicates this is a Playwright object */
83
  isPlaywright?: boolean;
84
  /** Get the browser instance (Puppeteer style) */
85
  browser?(): Browser;
86
  /** Puppeteer-style script evaluation on new documents */
87
  evaluateOnNewDocument?: Page['addInitScript'];
88
  /** Get CDP session client for advanced browser control */
89
  _client(): CDPSession;
90
}
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import { chromium } from "playwright-extra";
97

98
const browser = await chromium.launch();
99
const page = await browser.newPage();
100

101
// Puppeteer-style browser access
102
const browserFromPage = page.browser();
103
console.log('Browser from page:', browserFromPage);
104

105
// Puppeteer-style script injection
106
await page.evaluateOnNewDocument(() => {
107
  // This script runs on every new document
108
  console.log('Script injected via Puppeteer compatibility');
109
});
110

111
// CDP client access for advanced control
112
const client = page._client();
113
await client.send('Runtime.evaluate', {
114
  expression: 'console.log("CDP command executed")'
115
});
116
```
117

118
### CDP Session Management
119

120
The compatibility layer provides access to Chrome DevTools Protocol sessions for advanced browser control.
121

122
```typescript { .api }
123
/**
124
 * Get or create a CDP session for a page or frame
125
 * @param page - Page or Frame object to get CDP session for
126
 * @returns CDP session for the page/frame, or dummy client for non-Chromium browsers
127
 */
128
async function getPageCDPSession(page: Page | Frame): Promise<CDPSession>;
129

130
/**
131
 * Get or create a CDP session for a browser
132
 * @param browser - Browser object to get CDP session for  
133
 * @returns CDP session for the browser, or dummy client for non-Chromium browsers
134
 */
135
async function getBrowserCDPSession(browser: Browser): Promise<CDPSession>;
136

137
/**
138
 * Create a compatibility shim for a page or frame object
139
 * @param page - Page or Frame to enhance with Puppeteer compatibility
140
 * @returns Enhanced page/frame with Puppeteer-compatible methods
141
 */
142
function createPageShim(page: Page | Frame): Page | Frame;
143

144
/**
145
 * Create a compatibility shim for a browser object  
146
 * @param browser - Browser to enhance with Puppeteer compatibility
147
 * @returns Enhanced browser with Puppeteer-compatible methods
148
 */
149
function createBrowserShim(browser: Browser): Browser;
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
import { chromium } from "playwright-extra";
156

157
const browser = await chromium.launch();
158
const page = await browser.newPage();
159

160
// Access CDP through compatibility layer
161
const client = page._client();
162

163
// Send CDP commands
164
await client.send('Runtime.enable');
165
await client.send('Page.enable');
166

167
// Listen to CDP events
168
client.on('Runtime.consoleAPICalled', (event) => {
169
  console.log('Console API called:', event);
170
});
171

172
// Execute JavaScript via CDP
173
const result = await client.send('Runtime.evaluate', {
174
  expression: '2 + 2',
175
  returnByValue: true
176
});
177
console.log('Result:', result.result.value); // 4
178
```
179

180
### Advanced Compatibility Features
181

182
The compatibility layer includes several advanced features for seamless integration:
183

184
**User Agent Override:**
185

186
```typescript
187
import { chromium } from "playwright-extra";
188

189
const browser = await chromium.launch();
190
const page = await browser.newPage();
191

192
// Puppeteer-style user agent setting
193
await page.setUserAgent('Mozilla/5.0 (Custom Browser)');
194
```
195

196
**CSP Bypass:**
197

198
```typescript
199
import { chromium } from "playwright-extra";
200

201
const browser = await chromium.launch();
202
const page = await browser.newPage();
203

204
// Puppeteer-style CSP bypass
205
await page.setBypassCSP(true);
206
```
207

208
**Browser Version Info:**
209

210
```typescript
211
import { chromium } from "playwright-extra";
212

213
const browser = await chromium.launch();
214

215
// Get browser user agent (works even with launchPersistentContext)
216
const userAgent = await browser.userAgent();
217
console.log('Browser user agent:', userAgent);
218
```
219

220
### Compatibility Detection
221

222
Utility functions to detect and work with compatibility-enhanced objects:
223

224
```typescript { .api }
225
/**
226
 * Check if an object is a Playwright Page
227
 * @param obj - Object to check
228
 * @returns true if object is a Playwright Page
229
 */
230
function isPlaywrightPage(obj: unknown): obj is Page;
231

232
/**
233
 * Check if an object is a Playwright Frame
234
 * @param obj - Object to check
235
 * @returns true if object is a Playwright Frame
236
 */
237
function isPlaywrightFrame(obj: unknown): obj is Frame;
238

239
/**
240
 * Check if an object is a Playwright Browser
241
 * @param obj - Object to check
242
 * @returns true if object is a Playwright Browser
243
 */
244
function isPlaywrightBrowser(obj: unknown): obj is Browser;
245

246
/**
247
 * Check if an object has Puppeteer compatibility shim applied
248
 * @param obj - Object to check
249
 * @returns true if object has compatibility shim
250
 */
251
function isPuppeteerCompat(obj?: unknown): obj is PlaywrightObject;
252
```
253

254
**Usage Examples:**
255

256
```typescript
257
import { 
258
  isPlaywrightPage, 
259
  isPlaywrightBrowser, 
260
  isPuppeteerCompat 
261
} from "playwright-extra";
262

263
const browser = await chromium.launch();
264
const page = await browser.newPage();
265

266
// Type detection
267
console.log('Is Playwright browser:', isPlaywrightBrowser(browser)); // true
268
console.log('Is Playwright page:', isPlaywrightPage(page)); // true
269
console.log('Has compat shim:', isPuppeteerCompat(browser)); // true
270

271
// Safe method access based on type
272
if (isPlaywrightBrowser(browser) && isPuppeteerCompat(browser)) {
273
  const userAgent = await browser.userAgent();
274
  console.log('User agent:', userAgent);
275
}
276
```
277

278
### Plugin Integration
279

280
The compatibility layer automatically applies to plugin lifecycle events:
281

282
```typescript
283
class MyPuppeteerPlugin extends PuppeteerExtraPlugin {
284
  constructor(opts = {}) {
285
    super(opts);
286
  }
287

288
  get name() {
289
    return 'my-puppeteer-plugin';
290
  }
291

292
  async onPageCreated(page) {
293
    // page is automatically enhanced with Puppeteer compatibility
294
    const browser = page.browser(); // Puppeteer-style method
295
    const client = page._client();   // CDP client access
296
    
297
    // Original Playwright methods still work
298
    await page.goto('https://example.com');
299
  }
300

301
  async onBrowser(browser) {
302
    // browser is automatically enhanced with compatibility
303
    const pages = await browser.pages(); // Get all pages
304
    const userAgent = await browser.userAgent(); // Get user agent
305
  }
306
}
307
```
308

309
### Disabling Compatibility
310

311
Plugins can opt out of the compatibility layer if needed:
312

313
```typescript
314
class NativePlaywrightPlugin extends PuppeteerExtraPlugin {
315
  constructor(opts = {}) {
316
    super(opts);
317
    // Disable Puppeteer compatibility shim
318
    this.noPuppeteerShim = true;
319
  }
320

321
  get name() {
322
    return 'native-playwright-plugin';
323
  }
324

325
  async onPageCreated(page) {
326
    // page is the raw Playwright page object
327
    // No Puppeteer compatibility methods available
328
    await page.goto('https://example.com');
329
  }
330
}
331
```
332

333
## Core Types
334

335
```typescript { .api }
336
type PlaywrightObject = Page | Frame | Browser;
337

338
interface PuppeteerBrowserShim {
339
  isCompatShim?: boolean;
340
  isPlaywright?: boolean;
341
  pages?: BrowserContext['pages'];
342
  userAgent(): Promise<string>;
343
}
344

345
interface PuppeteerPageShim {
346
  isCompatShim?: boolean;
347
  isPlaywright?: boolean;
348
  browser?(): Browser;
349
  evaluateOnNewDocument?: Page['addInitScript'];
350
  _client(): CDPSession;
351
}
352

353
interface CDPSession {
354
  send(method: string, params?: any): Promise<any>;
355
  on(event: string, listener: (...args: any[]) => void): void;
356
}
357
```