--- title: "Cypress vs Puppeteer" slug: "cypress-vs-puppeteer" category: "comparisons" tags: ["comparisons", "cypress", "puppeteer", "testing", "browser-automation", "frontend"] status: "stable" last_updated: 2026-05-14 summary: "Pick Cypress for UI testing with developer experience; pick Puppeteer for scripted browser automation, scraping, or programmatic PDF generation." related: ["[[comparisons/playwright-vs-cypress]]", "[[coding/testing]]", "[[frontend/react]]", "[[frontend/nextjs]]", "[[backend/observability]]", "[[comparisons/vitest-vs-jest]]", "[[tooling/github-actions]]"] --- ## Overview Cypress and Puppeteer solve adjacent problems and rarely compete directly. Cypress is a test framework: it provides an assertion library, test runner, retry semantics, and developer tooling designed around the test-write-debug cycle. Puppeteer is a browser automation library: it gives you a Node.js API to drive a headless Chromium instance for any purpose, including tests. Pick Cypress when the goal is a UI test suite with good DX, time-travel debugging, and team-readable assertions. Pick Puppeteer (or Playwright, its spiritual successor) when the goal is programmatic browser control: scraping, crawling, generating PDFs, taking screenshots, or running custom automation that does not fit a test assertion model. See [[comparisons/playwright-vs-cypress]] for the Playwright-vs-Cypress decision, which supersedes this one for pure test suite choices. ## When Cypress wins Cypress is the right pick when the deliverable is a UI test suite that a team will write and maintain. - Built-in assertion retry: `cy.get('.btn').should('be.visible')` retries the DOM query automatically until the assertion passes or the timeout expires. Puppeteer requires manual polling or `waitForSelector`. - Time-travel debugger: every command captures a DOM snapshot; hovering over a step in the Cypress runner replays the page at that moment. Puppeteer has no equivalent. - Test isolation: Cypress clears state between tests by default; Puppeteer leaves browser state management to the script author. - `cy.intercept` stubs network requests at the test level; setting up equivalent mocks in Puppeteer requires a custom request interception layer. - Component testing: `cy.mount` runs React or Vue components in isolation without a full-page navigate. Puppeteer has no component test concept. - Error messages are human-readable and point to the failing assertion; Puppeteer timeout errors require reading a stack trace. ## When Puppeteer wins Puppeteer is the right pick for scripted automation that goes beyond test assertions. - PDF generation: `page.pdf()` renders a page to a PDF with print media queries applied; common for invoice, report, and certificate pipelines. - Screenshots and visual snapshots: `page.screenshot()` with full-page and clip options; useful for visual regression pipelines outside a test framework. - Web scraping and crawling: navigate, evaluate JavaScript in-page, extract DOM data, follow links. Cypress's same-origin model and test-runner structure make it the wrong tool for crawlers. - Automated form fill and submission against third-party services: Puppeteer scripts are easier to version and run as cron jobs outside CI. - DevTools Protocol access: Puppeteer exposes the full Chrome DevTools Protocol, including network throttling, CPU profiling, code coverage, and accessibility tree inspection. Cypress exposes a subset. - Performance audits: integrate with Lighthouse via `lighthouse(page.url(), {port})` to run Lighthouse against an authenticated session. ## Trade-offs at a glance | Dimension | Cypress | Puppeteer | | ---------------------- | ---------------------------------------- | --------------------------------------- | | Primary use case | UI test suite | Browser automation, scripting | | Assertion library | Built-in Chai-based | None; you bring your own | | Auto-retry | All commands retry | Manual polling required | | Time-travel debugging | Yes | No | | Network stubbing | `cy.intercept` | `page.setRequestInterception` | | Component testing | `cy.mount` for React, Vue | Not supported | | PDF generation | Not supported | `page.pdf()` | | Scraping | Not appropriate (same-origin limit) | Full multi-origin support | | DevTools Protocol | Limited | Full access | | Browser engines | Chromium, Firefox, WebKit (limited) | Chromium only | | Parallelism | Paid Cloud or manual sharding | Script-level async; unlimited | | License | MIT + paid Cloud | Apache 2.0 | ## Migration cost These tools are rarely swapped; the use cases are different enough that migration is usually a rewrite. - Cypress to Puppeteer: strip the assertion layer and Cypress commands; replace with raw `page` API calls and a test runner (Jest, Vitest). The DOM interaction patterns are similar; the retry and assertion semantics must be rebuilt. Plan two engineer-weeks for a 50-test suite. - Puppeteer to Cypress: only worth doing if automation scripts are being converted to a proper test suite. Cypress cannot replicate scraping, PDF, or cross-origin scripts. Plan one week to remap `page.click`/`page.type` to `cy.click`/`cy.type` for test cases. - Puppeteer to Playwright: the preferred upgrade path when Puppeteer is the bottleneck; Playwright is a multi-browser Puppeteer superset. See [[comparisons/playwright-vs-cypress]] for the full comparison. ## Recommendation - New UI test suite for a React or Next.js app: Cypress for DX, or Playwright for cross-browser coverage. See [[comparisons/playwright-vs-cypress]]. - Invoice or report PDF generation in a Node.js service: Puppeteer. `page.pdf()` is the standard approach. - Web scraper or crawler: Puppeteer or Playwright; Cypress is the wrong tool. - Visual regression testing at scale: Playwright with its built-in screenshot diffing, or Puppeteer feeding Percy or Chromatic. - Performance audit against an authenticated page: Puppeteer plus Lighthouse. ## Related - [[comparisons/playwright-vs-cypress]] - [[coding/testing]] - [[frontend/react]] - [[frontend/nextjs]] - [[backend/observability]] - [[comparisons/vitest-vs-jest]] - [[tooling/github-actions]]