puppeteer-testing

Overview

Puppeteer controls Chrome / Chromium via the DevTools Protocol - a lightweight fit (no bundled test runner) for Chrome-only browser automation beyond E2E testing: scraping, PDF generation, screenshot pipelines, web crawling.

When to use

• Chrome-only automation (no Firefox / WebKit needed).
• Use cases beyond E2E testing: scraping, PDF generation, screenshot capture, automated browsing for crawlers.
• Existing Puppeteer codebase; migration cost prohibitive.

For E2E testing specifically: Playwright is the recommended successor. Migration is mostly mechanical (similar API).

Step 1 - Install

npm install --save-dev puppeteer
# Auto-downloads matching Chromium

# Or for Chrome-bring-your-own:
npm install --save-dev puppeteer-core

puppeteer (full) bundles Chromium; puppeteer-core (lite) lets you point at an existing Chrome.

Verify: npm ls puppeteer lists the installed version. If you installed puppeteer-core, no Chromium is bundled - pass executablePath at launch or the next step throws Could not find Chromium.

Step 2 - Basic browser automation

// scripts/screenshot.js
import puppeteer from 'puppeteer';

(async () => {
  const browser = await puppeteer.launch({ headless: 'new' });
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({ path: 'example.png', fullPage: true });
  await browser.close();
})();

The page.* API mirrors Playwright's: page.goto, page.click, page.type, page.evaluate, etc.

Verify: after running, example.png exists and is non-empty. If it is missing or the script threw Could not find Chromium, the bundled download was skipped - reinstall puppeteer or set executablePath, confirm headless: 'new', then re-run.

Step 3 - E2E test (with Jest)

// __tests__/checkout.test.js
import puppeteer from 'puppeteer';

let browser, page;

beforeAll(async () => {
  browser = await puppeteer.launch({ headless: 'new' });
});

beforeEach(async () => {
  page = await browser.newPage();
  await page.setViewport({ width: 1280, height: 720 });
});

afterEach(async () => {
  await page.close();
});

afterAll(async () => {
  await browser.close();
});

test('checkout flow', async () => {
  await page.goto('http://localhost:3000/login');
  await page.type('[data-testid=email]', 'user@example.com');
  await page.type('[data-testid=password]', 'pwd');
  await page.click('button[type=submit]');

  await page.waitForSelector('h1');
  const heading = await page.$eval('h1', el => el.textContent);
  expect(heading).toContain('Welcome');
}, 60000);

Step 4 - Use-case recipes

Beyond the core automation and E2E spine above, Puppeteer covers network interception, server-side PDF generation, multi-viewport screenshot pipelines, and scraping. Copy-paste recipes for each: references/use-cases.md.

Step 5 - Run

node scripts/screenshot.js

# Or as part of test suite
npx jest

Step 6 - Migration to Playwright

When ready to migrate:

// Puppeteer
const browser = await puppeteer.launch();
const page = await browser.newPage();

// Playwright equivalent
const browser = await chromium.launch();
const page = await browser.newPage();

The APIs are similar; mechanical find-replace covers most cases. Playwright adds: cross-browser, web-first assertions, trace viewer, codegen - net win unless Chrome-only is intentional.

Anti-patterns

Limitations

• Chrome / Chromium only. No Firefox / WebKit.
• No bundled test runner. Pair with Jest / Mocha / Vitest.
• No web-first assertions. Manual waitForSelector patterns.
• Maintenance pace slower than Playwright. Active but not expanding.

References

• Puppeteer docs at pptr.dev.
• playwright-testing - recommended successor.
• testcafe-testing - alternative Chrome-friendly E2E.