cokit-cli 1.0.1 → 1.0.2

package/skills/ck-chrome-devtools/references/puppeteer-reference.md

@@ -0,0 +1,953 @@
+# Puppeteer Quick Reference
+
+Complete guide to browser automation with Puppeteer - a high-level API over Chrome DevTools Protocol.
+
+## Table of Contents
+
+- [Setup](#setup)
+- [Browser & Page Management](#browser--page-management)
+- [Navigation](#navigation)
+- [Element Interaction](#element-interaction)
+- [JavaScript Execution](#javascript-execution)
+- [Screenshots & PDFs](#screenshots--pdfs)
+- [Network Interception](#network-interception)
+- [Device Emulation](#device-emulation)
+- [Performance](#performance)
+- [Common Patterns](#common-patterns)
+
+---
+
+## Setup
+
+### Installation
+
+```bash
+# Install Puppeteer
+npm install puppeteer
+
+# Install core only (bring your own Chrome)
+npm install puppeteer-core
+```
+
+### Basic Usage
+
+```javascript
+import puppeteer from 'puppeteer';
+
+// Launch browser
+const browser = await puppeteer.launch({
+  headless: true,
+  args: ['--no-sandbox']
+});
+
+// Open page
+const page = await browser.newPage();
+
+// Navigate
+await page.goto('https://example.com');
+
+// Do work...
+
+// Cleanup
+await browser.close();
+```
+
+---
+
+## Browser & Page Management
+
+### Launch Browser
+
+```javascript
+const browser = await puppeteer.launch({
+  // Visibility
+  headless: false,              // Show browser UI
+  headless: 'new',              // New headless mode (Chrome 112+)
+
+  // Chrome location
+  executablePath: '/path/to/chrome',
+  channel: 'chrome',            // or 'chrome-canary', 'chrome-beta'
+
+  // Browser context
+  userDataDir: './user-data',   // Persistent profile
+
+  // Window size
+  defaultViewport: {
+    width: 1920,
+    height: 1080,
+    deviceScaleFactor: 1,
+    isMobile: false
+  },
+
+  // Advanced options
+  args: [
+    '--no-sandbox',
+    '--disable-setuid-sandbox',
+    '--disable-dev-shm-usage',
+    '--disable-web-security',
+    '--disable-features=IsolateOrigins',
+    '--disable-site-isolation-trials',
+    '--start-maximized'
+  ],
+
+  // Debugging
+  devtools: true,               // Open DevTools automatically
+  slowMo: 250,                  // Slow down by 250ms per action
+
+  // Network
+  proxy: {
+    server: 'http://proxy.com:8080'
+  }
+});
+```
+
+### Connect to Running Browser
+
+```javascript
+// Launch Chrome with debugging
+// google-chrome --remote-debugging-port=9222
+
+const browser = await puppeteer.connect({
+  browserURL: 'http://localhost:9222',
+  // or browserWSEndpoint: 'ws://localhost:9222/devtools/browser/...'
+});
+```
+
+### Page Management
+
+```javascript
+// Create new page
+const page = await browser.newPage();
+
+// Get all pages
+const pages = await browser.pages();
+
+// Close page
+await page.close();
+
+// Multiple pages
+const page1 = await browser.newPage();
+const page2 = await browser.newPage();
+
+// Switch between pages
+await page1.bringToFront();
+```
+
+### Browser Context (Incognito)
+
+```javascript
+// Create isolated context
+const context = await browser.createBrowserContext();
+const page = await context.newPage();
+
+// Cleanup context
+await context.close();
+```
+
+---
+
+## Navigation
+
+### Basic Navigation
+
+```javascript
+// Navigate to URL
+await page.goto('https://example.com');
+
+// Navigate with options
+await page.goto('https://example.com', {
+  waitUntil: 'networkidle2',    // or 'load', 'domcontentloaded', 'networkidle0'
+  timeout: 30000                 // Max wait time (ms)
+});
+
+// Reload page
+await page.reload({ waitUntil: 'networkidle2' });
+
+// Navigation history
+await page.goBack();
+await page.goForward();
+
+// Wait for navigation
+await page.waitForNavigation({
+  waitUntil: 'networkidle2'
+});
+```
+
+### Wait Until Options
+
+- `load` - Wait for load event
+- `domcontentloaded` - Wait for DOMContentLoaded event
+- `networkidle0` - Wait until no network connections for 500ms
+- `networkidle2` - Wait until max 2 network connections for 500ms
+
+---
+
+## Element Interaction
+
+### Selectors
+
+```javascript
+// CSS selectors
+await page.$('#id');
+await page.$('.class');
+await page.$('div > p');
+
+// XPath
+await page.$x('//button[text()="Submit"]');
+
+// Get all matching elements
+await page.$$('.item');
+await page.$$x('//div[@class="item"]');
+```
+
+### Click Elements
+
+```javascript
+// Click by selector
+await page.click('.button');
+
+// Click with options
+await page.click('.button', {
+  button: 'left',           // or 'right', 'middle'
+  clickCount: 1,            // 2 for double-click
+  delay: 100                // Delay between mousedown and mouseup
+});
+
+// ElementHandle click
+const button = await page.$('.button');
+await button.click();
+```
+
+### Type Text
+
+```javascript
+// Type into input
+await page.type('#search', 'query text');
+
+// Type with delay
+await page.type('#search', 'slow typing', { delay: 100 });
+
+// Clear and type
+await page.$eval('#search', el => el.value = '');
+await page.type('#search', 'new text');
+```
+
+### Form Interaction
+
+```javascript
+// Fill input
+await page.type('#username', 'john@example.com');
+await page.type('#password', 'secret123');
+
+// Select dropdown option
+await page.select('#country', 'US');           // By value
+await page.select('#country', 'USA', 'UK');    // Multiple
+
+// Check/uncheck checkbox
+await page.click('input[type="checkbox"]');
+
+// Choose radio button
+await page.click('input[value="option2"]');
+
+// Upload file
+const input = await page.$('input[type="file"]');
+await input.uploadFile('/path/to/file.pdf');
+
+// Submit form
+await page.click('button[type="submit"]');
+await page.waitForNavigation();
+```
+
+### Hover & Focus
+
+```javascript
+// Hover over element
+await page.hover('.menu-item');
+
+// Focus element
+await page.focus('#input');
+
+// Blur
+await page.$eval('#input', el => el.blur());
+```
+
+### Drag & Drop
+
+```javascript
+const source = await page.$('.draggable');
+const target = await page.$('.drop-zone');
+
+await source.drag(target);
+await source.drop(target);
+```
+
+---
+
+## JavaScript Execution
+
+### Evaluate in Page Context
+
+```javascript
+// Execute JavaScript
+const title = await page.evaluate(() => document.title);
+
+// With arguments
+const text = await page.evaluate(
+  (selector) => document.querySelector(selector).textContent,
+  '.heading'
+);
+
+// Return complex data
+const data = await page.evaluate(() => ({
+  title: document.title,
+  url: location.href,
+  cookies: document.cookie
+}));
+
+// With ElementHandle
+const element = await page.$('.button');
+const text = await page.evaluate(el => el.textContent, element);
+```
+
+### Query & Modify DOM
+
+```javascript
+// Get element property
+const value = await page.$eval('#input', el => el.value);
+
+// Get multiple elements
+const items = await page.$$eval('.item', elements =>
+  elements.map(el => el.textContent)
+);
+
+// Modify element
+await page.$eval('#input', (el, value) => {
+  el.value = value;
+}, 'new value');
+
+// Add class
+await page.$eval('.element', el => el.classList.add('active'));
+```
+
+### Expose Functions
+
+```javascript
+// Expose Node.js function to page
+await page.exposeFunction('md5', (text) =>
+  crypto.createHash('md5').update(text).digest('hex')
+);
+
+// Call from page context
+const hash = await page.evaluate(async () => {
+  return await window.md5('hello world');
+});
+```
+
+---
+
+## Screenshots & PDFs
+
+### Screenshots
+
+```javascript
+// Full page screenshot
+await page.screenshot({
+  path: 'screenshot.png',
+  fullPage: true
+});
+
+// Viewport screenshot
+await page.screenshot({
+  path: 'viewport.png',
+  fullPage: false
+});
+
+// Element screenshot
+const element = await page.$('.chart');
+await element.screenshot({
+  path: 'chart.png'
+});
+
+// Screenshot options
+await page.screenshot({
+  path: 'page.png',
+  type: 'png',              // or 'jpeg', 'webp'
+  quality: 80,              // JPEG quality (0-100)
+  clip: {                   // Crop region
+    x: 0,
+    y: 0,
+    width: 500,
+    height: 500
+  },
+  omitBackground: true      // Transparent background
+});
+
+// Screenshot to buffer
+const buffer = await page.screenshot();
+```
+
+### PDF Generation
+
+```javascript
+// Generate PDF
+await page.pdf({
+  path: 'page.pdf',
+  format: 'A4',             // or 'Letter', 'Legal', etc.
+  printBackground: true,
+  margin: {
+    top: '1cm',
+    right: '1cm',
+    bottom: '1cm',
+    left: '1cm'
+  }
+});
+
+// Custom page size
+await page.pdf({
+  path: 'custom.pdf',
+  width: '8.5in',
+  height: '11in',
+  landscape: true
+});
+
+// Header and footer
+await page.pdf({
+  path: 'report.pdf',
+  displayHeaderFooter: true,
+  headerTemplate: '<div style="font-size:10px;">Header</div>',
+  footerTemplate: '<div style="font-size:10px;">Page <span class="pageNumber"></span></div>'
+});
+```
+
+---
+
+## Network Interception
+
+### Request Interception
+
+```javascript
+// Enable request interception
+await page.setRequestInterception(true);
+
+// Intercept requests
+page.on('request', (request) => {
+  // Block specific resource types
+  if (request.resourceType() === 'image') {
+    request.abort();
+  }
+  // Block URLs
+  else if (request.url().includes('ads')) {
+    request.abort();
+  }
+  // Modify request
+  else if (request.url().includes('api')) {
+    request.continue({
+      headers: {
+        ...request.headers(),
+        'Authorization': 'Bearer token'
+      }
+    });
+  }
+  // Continue normally
+  else {
+    request.continue();
+  }
+});
+```
+
+### Mock Responses
+
+```javascript
+await page.setRequestInterception(true);
+
+page.on('request', (request) => {
+  if (request.url().includes('/api/user')) {
+    request.respond({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        id: 1,
+        name: 'Mock User'
+      })
+    });
+  } else {
+    request.continue();
+  }
+});
+```
+
+### Monitor Network
+
+```javascript
+// Track requests
+page.on('request', (request) => {
+  console.log('Request:', request.method(), request.url());
+});
+
+// Track responses
+page.on('response', (response) => {
+  console.log('Response:', response.status(), response.url());
+});
+
+// Track failed requests
+page.on('requestfailed', (request) => {
+  console.log('Failed:', request.failure().errorText, request.url());
+});
+
+// Get response body
+page.on('response', async (response) => {
+  if (response.url().includes('/api/data')) {
+    const json = await response.json();
+    console.log('API Data:', json);
+  }
+});
+```
+
+---
+
+## Device Emulation
+
+### Predefined Devices
+
+```javascript
+import { devices } from 'puppeteer';
+
+// Emulate iPhone
+const iPhone = devices['iPhone 13 Pro'];
+await page.emulate(iPhone);
+
+// Common devices
+const iPad = devices['iPad Pro'];
+const pixel = devices['Pixel 5'];
+const galaxy = devices['Galaxy S9+'];
+
+// Navigate after emulation
+await page.goto('https://example.com');
+```
+
+### Custom Device
+
+```javascript
+await page.emulate({
+  viewport: {
+    width: 375,
+    height: 812,
+    deviceScaleFactor: 3,
+    isMobile: true,
+    hasTouch: true,
+    isLandscape: false
+  },
+  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)...'
+});
+```
+
+### Viewport Only
+
+```javascript
+await page.setViewport({
+  width: 1920,
+  height: 1080,
+  deviceScaleFactor: 1
+});
+```
+
+### Geolocation
+
+```javascript
+// Set geolocation
+await page.setGeolocation({
+  latitude: 37.7749,
+  longitude: -122.4194,
+  accuracy: 100
+});
+
+// Grant permissions
+const context = browser.defaultBrowserContext();
+await context.overridePermissions('https://example.com', ['geolocation']);
+```
+
+### Timezone & Locale
+
+```javascript
+// Set timezone
+await page.emulateTimezone('America/New_York');
+
+// Set locale
+await page.emulateMediaType('screen');
+await page.evaluateOnNewDocument(() => {
+  Object.defineProperty(navigator, 'language', {
+    get: () => 'en-US'
+  });
+});
+```
+
+---
+
+## Performance
+
+### CPU & Network Throttling
+
+```javascript
+// CPU throttling
+const client = await page.createCDPSession();
+await client.send('Emulation.setCPUThrottlingRate', { rate: 4 });
+
+// Network throttling
+await page.emulateNetworkConditions({
+  offline: false,
+  downloadThroughput: 1.5 * 1024 * 1024 / 8, // 1.5 Mbps
+  uploadThroughput: 750 * 1024 / 8,           // 750 Kbps
+  latency: 40                                  // 40ms RTT
+});
+
+// Predefined profiles
+await page.emulateNetworkConditions(
+  puppeteer.networkConditions['Fast 3G']
+);
+
+// Disable throttling
+await page.emulateNetworkConditions({
+  offline: false,
+  downloadThroughput: -1,
+  uploadThroughput: -1,
+  latency: 0
+});
+```
+
+### Performance Metrics
+
+```javascript
+// Get metrics
+const metrics = await page.metrics();
+console.log(metrics);
+// {
+//   Timestamp, Documents, Frames, JSEventListeners,
+//   Nodes, LayoutCount, RecalcStyleCount,
+//   LayoutDuration, RecalcStyleDuration,
+//   ScriptDuration, TaskDuration,
+//   JSHeapUsedSize, JSHeapTotalSize
+// }
+```
+
+### Performance Tracing
+
+```javascript
+// Start tracing
+await page.tracing.start({
+  path: 'trace.json',
+  categories: [
+    'devtools.timeline',
+    'disabled-by-default-devtools.timeline'
+  ]
+});
+
+// Navigate
+await page.goto('https://example.com');
+
+// Stop tracing
+await page.tracing.stop();
+
+// Analyze trace in chrome://tracing
+```
+
+### Coverage (Code Usage)
+
+```javascript
+// Start JS coverage
+await page.coverage.startJSCoverage();
+
+// Start CSS coverage
+await page.coverage.startCSSCoverage();
+
+// Navigate
+await page.goto('https://example.com');
+
+// Stop and get coverage
+const jsCoverage = await page.coverage.stopJSCoverage();
+const cssCoverage = await page.coverage.stopCSSCoverage();
+
+// Calculate unused bytes
+let totalBytes = 0;
+let usedBytes = 0;
+for (const entry of [...jsCoverage, ...cssCoverage]) {
+  totalBytes += entry.text.length;
+  for (const range of entry.ranges) {
+    usedBytes += range.end - range.start - 1;
+  }
+}
+
+console.log(`Used: ${usedBytes / totalBytes * 100}%`);
+```
+
+---
+
+## Common Patterns
+
+### Wait for Elements
+
+```javascript
+// Wait for selector
+await page.waitForSelector('.element', {
+  visible: true,
+  timeout: 5000
+});
+
+// Wait for XPath
+await page.waitForXPath('//button[text()="Submit"]');
+
+// Wait for function
+await page.waitForFunction(
+  () => document.querySelector('.loading') === null,
+  { timeout: 10000 }
+);
+
+// Wait for timeout
+await page.waitForTimeout(2000);
+```
+
+### Handle Dialogs
+
+```javascript
+// Alert, confirm, prompt
+page.on('dialog', async (dialog) => {
+  console.log(dialog.type(), dialog.message());
+
+  // Accept
+  await dialog.accept();
+  // or reject
+  // await dialog.dismiss();
+  // or provide input for prompt
+  // await dialog.accept('input text');
+});
+```
+
+### Handle Downloads
+
+```javascript
+// Set download path
+const client = await page.createCDPSession();
+await client.send('Page.setDownloadBehavior', {
+  behavior: 'allow',
+  downloadPath: '/path/to/downloads'
+});
+
+// Trigger download
+await page.click('a[download]');
+```
+
+### Multiple Pages (Tabs)
+
+```javascript
+// Listen for new pages
+browser.on('targetcreated', async (target) => {
+  if (target.type() === 'page') {
+    const newPage = await target.page();
+    console.log('New page opened:', newPage.url());
+  }
+});
+
+// Click link that opens new tab
+const [newPage] = await Promise.all([
+  new Promise(resolve => browser.once('targetcreated', target => resolve(target.page()))),
+  page.click('a[target="_blank"]')
+]);
+
+console.log('New page URL:', newPage.url());
+```
+
+### Frames (iframes)
+
+```javascript
+// Get all frames
+const frames = page.frames();
+
+// Find frame by name
+const frame = page.frames().find(f => f.name() === 'myframe');
+
+// Find frame by URL
+const frame = page.frames().find(f => f.url().includes('example.com'));
+
+// Main frame
+const mainFrame = page.mainFrame();
+
+// Interact with frame
+await frame.click('.button');
+await frame.type('#input', 'text');
+```
+
+### Infinite Scroll
+
+```javascript
+async function autoScroll(page) {
+  await page.evaluate(async () => {
+    await new Promise((resolve) => {
+      let totalHeight = 0;
+      const distance = 100;
+      const timer = setInterval(() => {
+        const scrollHeight = document.body.scrollHeight;
+        window.scrollBy(0, distance);
+        totalHeight += distance;
+
+        if (totalHeight >= scrollHeight) {
+          clearInterval(timer);
+          resolve();
+        }
+      }, 100);
+    });
+  });
+}
+
+await autoScroll(page);
+```
+
+### Cookies
+
+```javascript
+// Get cookies
+const cookies = await page.cookies();
+
+// Set cookies
+await page.setCookie({
+  name: 'session',
+  value: 'abc123',
+  domain: 'example.com',
+  path: '/',
+  httpOnly: true,
+  secure: true,
+  sameSite: 'Strict'
+});
+
+// Delete cookies
+await page.deleteCookie({ name: 'session' });
+```
+
+### Local Storage
+
+```javascript
+// Set localStorage
+await page.evaluate(() => {
+  localStorage.setItem('key', 'value');
+});
+
+// Get localStorage
+const value = await page.evaluate(() => {
+  return localStorage.getItem('key');
+});
+
+// Clear localStorage
+await page.evaluate(() => localStorage.clear());
+```
+
+### Error Handling
+
+```javascript
+try {
+  await page.goto('https://example.com', {
+    waitUntil: 'networkidle2',
+    timeout: 30000
+  });
+} catch (error) {
+  if (error.name === 'TimeoutError') {
+    console.error('Page load timeout');
+  } else {
+    console.error('Navigation failed:', error);
+  }
+
+  // Take screenshot on error
+  await page.screenshot({ path: 'error.png' });
+}
+```
+
+### Stealth Mode (Avoid Detection)
+
+```javascript
+// Hide automation indicators
+await page.evaluateOnNewDocument(() => {
+  // Override navigator.webdriver
+  Object.defineProperty(navigator, 'webdriver', {
+    get: () => false
+  });
+
+  // Mock chrome object
+  window.chrome = {
+    runtime: {}
+  };
+
+  // Mock permissions
+  const originalQuery = window.navigator.permissions.query;
+  window.navigator.permissions.query = (parameters) => (
+    parameters.name === 'notifications' ?
+      Promise.resolve({ state: 'granted' }) :
+      originalQuery(parameters)
+  );
+});
+
+// Set realistic user agent
+await page.setUserAgent(
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+);
+```
+
+---
+
+## Debugging Tips
+
+### Take Screenshots on Error
+
+```javascript
+page.on('pageerror', async (error) => {
+  console.error('Page error:', error);
+  await page.screenshot({ path: `error-${Date.now()}.png` });
+});
+```
+
+### Console Logging
+
+```javascript
+// Forward console to Node
+page.on('console', (msg) => {
+  console.log('PAGE LOG:', msg.text());
+});
+```
+
+### Slow Down Execution
+
+```javascript
+const browser = await puppeteer.launch({
+  slowMo: 250  // 250ms delay between actions
+});
+```
+
+### Keep Browser Open
+
+```javascript
+const browser = await puppeteer.launch({
+  headless: false,
+  devtools: true
+});
+
+// Prevent auto-close
+await page.evaluate(() => debugger);
+```
+
+---
+
+## Best Practices
+
+1. **Always close browser:** Use try/finally or process cleanup
+2. **Wait appropriately:** Use waitForSelector, not setTimeout
+3. **Handle errors:** Wrap navigation in try/catch
+4. **Optimize selectors:** Use specific selectors for reliability
+5. **Avoid race conditions:** Wait for navigation after clicks
+6. **Reuse pages:** Don't create new pages unnecessarily
+7. **Set timeouts:** Always specify reasonable timeouts
+8. **Clean up:** Close unused pages and contexts
+
+---
+
+## Resources
+
+- [Puppeteer Documentation](https://pptr.dev/)
+- [Puppeteer API](https://pptr.dev/api)
+- [Puppeteer Examples](https://github.com/puppeteer/puppeteer/tree/main/examples)
+- [Awesome Puppeteer](https://github.com/transitive-bullshit/awesome-puppeteer)