Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/scripts/puppeteer/SETUP.md

5.4 KiB
Raw Blame History

Puppeteer Setup Guide

Quick setup guide for AI agents using Puppeteer with docs-v2.

Installation

Option 1: Use System Chrome (Recommended for network-restricted environments)

# Install Puppeteer without downloading Chrome
PUPPETEER_SKIP_DOWNLOAD=true yarn install

Then use the --chrome flag to point to your system Chrome:

yarn debug:browser /influxdb3/core/ --chrome "/usr/bin/google-chrome"

Find your Chrome path:

# macOS
which google-chrome-stable
# Usually: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

# Linux
which google-chrome
# Usually: /usr/bin/google-chrome or /usr/bin/chromium

# Windows (PowerShell)
Get-Command chrome
# Usually: C:\Program Files\Google\Chrome\Application\chrome.exe

Option 2: Install Puppeteer's Bundled Chrome (Requires network access)

# Regular installation (downloads Chrome)
yarn install

# Or install Puppeteer browser separately
npx puppeteer browsers install chrome

Verification

Step 1: Check dependencies

# Check if Puppeteer is in package.json
grep puppeteer package.json

Should show:

"puppeteer": "^23.11.1",

Step 2: Start Hugo server

# Start Hugo development server
npx hugo server

Should show:

Web Server is available at http://localhost:1313/

Step 3: Test Puppeteer

# Test screenshot tool
yarn debug:screenshot / --output test-screenshot.png

If successful, you'll see:

📸 Screenshot Utility
=====================

URL: http://localhost:1313/
Viewport: 1280x720
Output: test-screenshot.png

Navigating to: http://localhost:1313/
✓ Page loaded successfully
✓ Screenshot saved: test-screenshot.png

✓ Screenshot captured successfully

Step 4: Verify screenshot was created

ls -lh test-screenshot.png

Should show a PNG file (typically 100-500KB).

Troubleshooting

Issue: "Failed to launch browser"

Error message:

Failed to launch browser: Could not find Chrome

Solution: Use system Chrome with --chrome flag:

# Find Chrome path
which google-chrome

# Use with Puppeteer
yarn debug:browser / --chrome "$(which google-chrome)"

Issue: "Failed to navigate to http://localhost:1313"

Error message:

Failed to navigate to http://localhost:1313/: net::ERR_CONNECTION_REFUSED

Solution: Start Hugo server:

npx hugo server

Issue: "PUPPETEER_SKIP_DOWNLOAD not working"

Error message:

ERROR: Failed to set up chrome-headless-shell

Solution: Set environment variable before yarn command:

# Correct
PUPPETEER_SKIP_DOWNLOAD=true yarn install

# Won't work
yarn install PUPPETEER_SKIP_DOWNLOAD=true

Issue: "Command not found: yarn"

Solution: Install Yarn or use npm:

# Install Yarn
npm install -g yarn

# Or use npm instead
npm run debug:screenshot -- / --output test.png

Quick Test Script

Save this as test-puppeteer-setup.js and run with node test-puppeteer-setup.js:

#!/usr/bin/env node

/**
 * Quick test to verify Puppeteer setup
 */

import { launchBrowser, navigateToPage, takeScreenshot } from './utils/puppeteer-helpers.js';

async function test() {
  console.log('\n🧪 Testing Puppeteer Setup\n');

  let browser;
  try {
    // 1. Launch browser
    console.log('1. Launching browser...');
    browser = await launchBrowser({ headless: true });
    console.log('   ✓ Browser launched\n');

    // 2. Navigate to home page
    console.log('2. Navigating to home page...');
    const page = await navigateToPage(browser, '/');
    console.log('   ✓ Page loaded\n');

    // 3. Take screenshot
    console.log('3. Taking screenshot...');
    await takeScreenshot(page, 'test-screenshot.png');
    console.log('   ✓ Screenshot saved\n');

    // 4. Get page title
    console.log('4. Getting page title...');
    const title = await page.title();
    console.log(`   ✓ Title: "${title}"\n`);

    console.log('✅ All tests passed!\n');
    console.log('Puppeteer is set up correctly and ready to use.\n');
  } catch (error) {
    console.error('\n❌ Test failed:', error.message);
    console.error('\nSee SETUP.md for troubleshooting steps.\n');
    process.exit(1);
  } finally {
    if (browser) {
      await browser.close();
    }
  }
}

test();

Run the test:

cd scripts/puppeteer
node test-puppeteer-setup.js

Environment Variables

You can set these environment variables to customize Puppeteer behavior:

# Skip downloading Puppeteer's bundled Chrome
export PUPPETEER_SKIP_DOWNLOAD=true

# Use custom Chrome path
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome

# Disable headless mode by default
export PUPPETEER_HEADLESS=false

Add to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make permanent.

Next Steps

Once setup is verified:

  1. Read the main README: README.md
  2. Try the debugging tools: 
    yarn debug:inspect /influxdb3/core/
yarn debug:screenshot /influxdb3/core/ --full-page
yarn debug:browser /influxdb3/core/ --devtools
  3. Create custom scripts using the helper functions
  4. Integrate into your workflow for testing and debugging

Getting Help