npm - @hienlh/ppm - Versions diffs - 0.9.81 → 0.9.83 - Mend

@hienlh/ppm 0.9.81 → 0.9.83

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1754) hide show

package/.opencode/skills/chrome-devtools/references/puppeteer-reference.md DELETED Viewed

@@ -1,953 +0,0 @@
-# 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)