# Puppeteer
Puppeteer is a Node.js library developed by Google that provides a high-level API to control Chrome or Chromium browsers over the [[Chrome DevTools Protocol (CDP)]]. It runs in headless mode by default but can be configured to run in full ("headed") mode.
First released in 2017 by the Google Chrome team.
## Key Features
### Browser Automation
- Navigate pages and interact with elements
- Fill forms and click buttons
- Handle dialogs and popups
- Manage cookies and localStorage
- Emulate devices and network conditions
### Screenshot & PDF Generation
- Capture full-page or element screenshots
- Generate PDFs from web pages
- Support for various image formats
### Web Scraping
- Extract data from dynamic (JavaScript-rendered) pages
- Wait for content to load
- Handle infinite scroll and pagination
### Testing
- End-to-end testing of web applications
- Visual regression testing
- Performance testing and metrics
### Performance Analysis
- Capture performance traces
- Measure Core Web Vitals
- Network request analysis
## Installation
```bash
# npm
npm install puppeteer
# yarn
yarn add puppeteer
# pnpm
pnpm add puppeteer
```
Note: Puppeteer downloads a compatible Chromium binary by default. Use `puppeteer-core` to use your own browser installation.
## Basic Usage
### Simple Navigation
```javascript
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });
await browser.close();
})();
```
### Form Interaction
```javascript
await page.type('#username', 'myuser');
await page.type('#password', 'mypassword');
await page.click('#login-button');
await page.waitForNavigation();
```
### Extract Content
```javascript
const title = await page.title();
const text = await page.$eval('.content', el => el.textContent);
const links = await page.$eval('a', anchors => anchors.map(a => a.href));
```
### Generate PDF
```javascript
await page.goto('https://example.com');
await page.pdf({
path: 'page.pdf',
format: 'A4',
printBackground: true
});
```
### Connect to Existing Browser
```javascript
// Connect to Chrome running with --remote-debugging-port=9222
const browser = await puppeteer.connect({
browserURL: 'http://localhost:9222'
});
```
See [[Chrome Debug Mode]] for running Chrome with debugging enabled.
## Configuration Options
### Launch Options
```javascript
const browser = await puppeteer.launch({
headless: false, // Show browser window
slowMo: 100, // Slow down operations (ms)
devtools: true, // Open DevTools
args: [
'--window-size=1920,1080',
'--disable-extensions'
]
});
```
### Page Options
```javascript
await page.setViewport({ width: 1920, height: 1080 });
await page.setUserAgent('Custom User Agent');
await page.setExtraHTTPHeaders({ 'Accept-Language': 'en-US' });
```
## Waiting Strategies
```javascript
// Wait for selector
await page.waitForSelector('.element');
// Wait for navigation
await page.waitForNavigation();
// Wait for network idle
await page.waitForNetworkIdle();
// Wait for function
await page.waitForFunction('document.querySelector(".done")');
// Custom timeout
await page.waitForSelector('.element', { timeout: 5000 });
```
## Puppeteer vs Playwright
| Feature | Puppeteer | [[Playwright]] |
|---------|-----------|------------|
| Browsers | Chrome/Chromium | Chrome, Firefox, Safari |
| Developer | Google | Microsoft |
| Language | JavaScript/TypeScript | JS, Python, .NET, Java |
| Auto-wait | Manual | Built-in |
| Parallelism | Manual | Built-in contexts |
| Mobile | Emulation only | Emulation only |
For cross-browser testing, consider [[Playwright]].
## Related
- [[Chrome DevTools Protocol (CDP)]] - Underlying protocol
- [[Chrome Debug Mode]] - Running Chrome with debugging
- [[Chrome DevTools]] - Browser developer tools
- [[Playwright]] - Cross-browser alternative
- [[socat]] - Bridge remote debugging connections
## References
- Official Documentation: https://pptr.dev/
- GitHub: https://github.com/puppeteer/puppeteer
- API Reference: https://pptr.dev/api
- Chrome DevTools Protocol: https://chromedevtools.github.io/devtools-protocol/