Setup
On first use, read
setup.md
for integration guidelines.
When to Use
User needs browser automation: web scraping, E2E testing, PDF generation, screenshots, or any headless Chrome task. Agent handles page navigation, element interaction, waiting strategies, and data extraction.
Architecture
Scripts and outputs in
~/puppeteer/
. See
memory-template.md
for structure.
~/puppeteer/
├── memory.md # Status + preferences
├── scripts/ # Reusable automation scripts
└── output/ # Screenshots, PDFs, scraped data
Quick Reference
| Topic | File |
|---|
| Setup process | setup.md
|
| Memory template | memory-template.md
|
| Selectors guide | selectors.md
|
| Waiting patterns | waiting.md
|
Core Rules
1. Always Wait Before Acting
Never click or type immediately after navigation. Always wait for the element:
await page.waitForSelector('#button');
await page.click('#button');
Clicking without waiting causes "element not found" errors 90% of the time.
2. Use Specific Selectors
Prefer stable selectors in this order:
[data-testid="submit"]
— test attributes (most stable)#unique-id
— IDsform button[type="submit"]
— semantic combinations.class-name
— classes (least stable, changes often)
Avoid:
div > div > div > button
— breaks on any DOM change.
3. Handle Navigation Explicitly
After clicks that navigate, wait for navigation:
await Promise.all([
page.waitForNavigation(),
page.click('a.next-page')
]);
Without this, the script continues before the new page loads.
4. Set Realistic Viewport
Always set viewport for consistent rendering:
await page.setViewport({ width: 1280, height: 800 });
Default viewport is 800x600 — many sites render differently or show mobile views.
5. Handle Popups and Dialogs
Dismiss dialogs before they block interaction:
page.on('dialog', async dialog => {
await dialog.dismiss(); // or dialog.accept()
});
Unhandled dialogs freeze the script.
6. Close Browser on Errors
Always wrap in try/finally:
const browser = await puppeteer.launch();
try {
// ... automation code
} finally {
await browser.close();
}
Leaked browser processes consume memory and ports.
7. Respect Rate Limits
Add delays between requests to avoid blocks:
await page.waitForTimeout(1000 + Math.random() * 2000);
Hammering sites triggers CAPTCHAs and IP bans.
Common Traps
page.click()
on invisible element → fails silently, use waitForSelector
with visible: true
- Screenshots of elements off-screen → blank image, scroll into view first
page.evaluate()
returns undefined → cannot return DOM nodes, only serializable data- Headless blocked by site → use
headless: 'new'
or set user agent
- Form submit reloads page →
page.waitForNavigation()
or data is lost
- Shadow DOM elements invisible to selectors → use
page.evaluateHandle()
to pierce shadow roots
- Cookies not persisting → launch with
userDataDir
for session persistence
Security & Privacy
Data that stays local:
- All scraped data in ~/puppeteer/output/
- Browser profile in specified userDataDir
This skill does NOT:
- Send scraped data anywhere
- Store credentials (you provide them per-script)
- Access files outside ~/puppeteer/
Related Skills
Install with
clawhub install <slug>
if user confirms:
playwright
— Cross-browser automation alternativechrome
— Chrome DevTools and debuggingweb
— General web development
Feedback
- If useful:
clawhub star puppeteer
- Stay updated:
clawhub sync
