LLM Best Practices

Cypress vs Puppeteer

Last updated 3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Use Cypress when the deliverable is a UI test suite; use Puppeteer when the deliverable is a script that drives a browser. They are a test framework and an automation library, so they rarely compete. Puppeteer 25 controls Chrome through the DevTools Protocol and Firefox through WebDriver BiDi, and runs headless by default. Playwright overlaps both: it is a test runner plus an automation API across three engines. For pure test-suite choices see playwright-vs-cypress.

Comparison

DimensionCypress 16Puppeteer 25
PurposeTest runner with assertions, retries, and runner UIBrowser automation library; bring your own test runner
BrowsersChrome, Edge, Firefox; WebKit experimental; Electron deprecatedChrome and Firefox
Retry and waitingCommands and assertions retry automaticallyExplicit waits (waitForSelector) and your own assertions
Network controlcy.interceptpage.setRequestInterception and CDP
Component testscy.mountNone
PDF and screenshotsScreenshots onlypage.pdf() and page.screenshot()
Scraping and crawlingPoor fitDesigned for it
Protocol accessLimitedChrome DevTools Protocol sessions

Pick Cypress when

Pick Cypress for a team-maintained UI test suite.

  • Retrying queries and assertions remove most timing code.
  • The interactive runner shows each command’s DOM snapshot, which speeds up debugging.
  • Component tests and cy.intercept stubs sit beside end-to-end tests.

Pick Puppeteer when

Pick Puppeteer for jobs that are not test assertions.

  • Generate PDFs from HTML with page.pdf() (print CSS applies); common for invoices and reports.
  • Take screenshots, crawl and scrape across origins, and run scheduled automation; for visual regression, compare screenshots with Playwright’s toHaveScreenshot or a service such as Percy or Chromatic.
  • Use CDP for tracing, coverage, throttling, or running Lighthouse against an authenticated page.
  • If you need these plus tests, or WebKit, use Playwright instead: its page.pdf() also works in Chromium, and its test runner is built in.

Migrate

These tools are seldom swapped. Cypress to Puppeteer means replacing cy.* commands with page calls and adding a runner (Vitest or Jest) with explicit waits. Puppeteer to Playwright is the lowest-effort upgrade when you need multiple browsers or tests; the API is close. See testing for test strategy.

FAQ

Should I use Puppeteer for end-to-end testing?

No for a team-maintained UI test suite; Puppeteer is an automation library with no built-in assertions or retries, so use Cypress. If you need tests plus scripting or WebKit, use Playwright.

Can Cypress generate PDFs?

No; Cypress takes screenshots only. Use Puppeteer’s page.pdf() for invoices and reports, or Playwright’s page.pdf() in Chromium.

Is Playwright a replacement for both Cypress and Puppeteer?

Playwright covers both jobs: it is a test runner plus an automation API across three engines. Puppeteer to Playwright is the lowest-effort upgrade because the API is close.

Backlinks