Frontend

Puppeteer vs. Playwright: A Field Manual from Install to Enterprise E2E

By 90后晨仔 · Aug 29, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Choosing between Puppeteer and Playwright is a recurring infrastructure decision for any team doing browser automation, scraping, PDF generation, or E2E testing. Getting the install right — especially in Docker and CI — and knowing which framework ships auto-waiting, visual regression, and trace debugging out of the box directly determines how much flakiness and boilerplate a project absorbs.

Summary

Puppeteer (Google) and Playwright (Microsoft) are the two dominant browser-automation libraries in the Node.js ecosystem, but their install footprints, API ergonomics, and testing capabilities diverge sharply. This guide walks through every supported installation method for both — standard, core-only, system-Chrome, Docker, and mirror-accelerated — along with the exact system dependencies each requires on Linux. It then catalogues the full command surface: launching browsers, page navigation, locator strategies, network interception, cookie and storage management, multi-tab and iframe handling, screenshot and PDF generation, and performance tracing.

Playwright’s built-in test framework gets its own section, with configuration, assertions, parallel projects, and CI integration spelled out. The debugging stack — Codegen, Trace Viewer, Inspector, and UI Mode — is documented with CLI invocations. A side-by-side quick-reference table maps common automation tasks to the equivalent Puppeteer and Playwright calls, and a decision flowchart at the end matches use cases (lightweight scripting vs. cross-browser E2E vs. enterprise test platforms) to the right tool.

Takeaways

— Puppeteer downloads a matching Chromium automatically (~170 MB); puppeteer-core skips the browser and requires an explicit executablePath, saving ~165 MB for CI images that already have Chrome.

— Playwright’s `npm init playwright@latest` wizard scaffolds a full E2E project with TypeScript, example specs, GitHub Actions workflow, and config in one command.

— Playwright browsers must be downloaded separately via `npx playwright install` — `npm install playwright` alone does not fetch them.

— Both tools support Chinese mirror acceleration: set `PUPPETEER_DOWNLOAD_BASE_URL` or `PLAYWRIGHT_DOWNLOAD_HOST` to the npmmirror URLs to avoid Google/Microsoft CDN timeouts.

— On Linux, Puppeteer’s Chromium needs ~20 system libraries installed manually; Playwright’s `npx playwright install-deps` auto-detects and installs missing dependencies.

— Playwright’s official Docker image `mcr.microsoft.com/playwright:v1.48.0-noble` ships all three browsers and system deps pre-installed; Puppeteer in Docker requires `--no-sandbox` and `--disable-setuid-sandbox` flags.

— Playwright’s locator system prioritizes `getByRole`, `getByLabel`, `getByText`, and `getByTestId` over raw CSS/XPath, aligning with accessibility semantics and reducing selector brittleness.

— Built-in auto-waiting in Playwright means `click`, `fill`, and assertions automatically retry until the element is actionable; Puppeteer requires explicit `waitForSelector` or `waitForFunction` calls.

— Playwright Test includes `toHaveScreenshot()` for visual regression, `storageState` for persisting authentication across tests, and `BrowserContext` for isolated multi-tenant parallel runs.

— Playwright’s debugging suite — `codegen` (record-and-generate), `--debug` (step-through Inspector), `--ui` (visual test runner), and `show-trace` (time-travel viewer) — has no equivalent in Puppeteer’s stock distribution.

— A decision flowchart closes the guide: Puppeteer for lightweight Chrome-only scripting and PDFs; Playwright for cross-browser E2E, enterprise test platforms, and multi-language (Python/Java/.NET) teams.

Conclusions

The installation complexity gap between the two tools is underappreciated: Playwright’s wizard and `install-deps` command collapse what is a multi-step, distro-specific manual process for Puppeteer into a single CLI invocation.

Playwright’s locator philosophy — role, label, text, test-id — is not just an API preference; it encodes an opinion that selectors should survive DOM refactors, which directly reduces flaky-test triage time in large suites.

Puppeteer’s `puppeteer-core` package is a deliberate design for headless environments, but the guide’s explicit warning against mixing `puppeteer` and `puppeteer-core` in the same project highlights a footgun that new users routinely hit.

The side-by-side quick-reference table reveals that for basic operations (screenshot, PDF, click, type, evaluate) the APIs are nearly identical, suggesting that the real switching cost is not syntax but the surrounding test infrastructure and debugging tooling.

Playwright’s `storageState` mechanism and project dependencies in the config file solve the ‘log in once, reuse across tests’ problem declaratively; Puppeteer requires manual cookie serialization with `fs.writeFileSync`, which is fragile across browser versions.

Concepts & terms

Browser Context (Playwright)

An isolated browser session with its own cookies, localStorage, and permissions. Multiple contexts can coexist in a single browser instance, enabling parallel multi-tenant testing without cross-contamination.

Auto-Waiting (Playwright)

Playwright automatically waits for elements to be attached, visible, stable, and enabled before performing actions like click or fill, and retries assertions until they pass or time out. This eliminates most explicit sleep/waitForSelector calls.

Chrome DevTools Protocol (CDP)

The low-level websocket-based protocol that Puppeteer uses to instrument Chrome/Chromium. It exposes domains like Page, Network, and Performance for direct browser control and metric collection.

puppeteer-core

A lightweight Puppeteer package that omits the bundled Chromium download. It requires the caller to supply an `executablePath` to an existing Chrome/Chromium installation, making it suitable for CI and Docker environments where the browser is already present.

storageState (Playwright)

A JSON-serializable snapshot of a browser context’s cookies and localStorage origins. It can be saved after login and loaded into subsequent contexts to skip authentication steps across tests.

Playwright Codegen

A CLI tool that opens a browser window and records user interactions, generating executable Playwright scripts in JavaScript, TypeScript, Python, Java, or C#. It supports device emulation, color scheme, and saved authentication state during recording.

Trace Viewer (Playwright)

A time-travel debugging tool that records DOM snapshots, network requests, console logs, and action steps during a test run. Developers can step forward and backward through the trace to inspect the page state at any point.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗