Skip to main content
Version: 21.6.1

FAQ

Q: Who maintains Puppeteer?​

The Chrome Browser Automation team maintains the library, but we'd love your help and expertise on the project! See our contributing guide.

Q: What is the status of cross-browser support?​

Official Firefox support is currently experimental. The ongoing collaboration with Mozilla aims to support common end-to-end testing use cases, for which developers expect cross-browser coverage. The Puppeteer team needs input from users to stabilize Firefox support and to bring missing APIs to our attention.

From Puppeteer v2.1.0 onwards you can specify puppeteer.launch({product: 'firefox'}) to run your Puppeteer scripts in Firefox Nightly, without any additional custom patches. While an older experiment required a patched version of Firefox, the current approach works with “stock” Firefox.

We will continue to collaborate with other browser vendors to bring Puppeteer support to browsers such as Safari. This effort includes exploration of a standard for executing cross-browser commands (instead of relying on the non-standard DevTools Protocol used by Chrome).

Update 2023-11-17: Puppeteer has experimental support for the new WebDriverBiDi protocol that can be used to automate Firefox. The WebDriver BiDi implementation in Firefox will replace the current CDP implementation in Firefox in the future. See https://pptr.dev/webdriver-bidi for more details.

Q: Does Puppeteer support WebDriver BiDi?​

Puppeteer has experimental support for WebDriver BiDi. See https://pptr.dev/webdriver-bidi.

Q: What are Puppeteer’s goals and principles?​

The goals of the project are:

  • Provide a reference implementation that highlights the capabilities of the Chrome DevTools and WebDriver BiDi protocols.
  • Grow the adoption of automated cross-browser testing.
  • Help dogfood new DevTools Protocol and WebDriver BiDi features...and catch bugs!
  • Learn more about the pain points of automated browser testing and help fill those gaps.

We adapt Chromium principles to help us drive product decisions:

  • Speed: Puppeteer has almost zero performance overhead over an automated page.
  • Security: Puppeteer operates off-process with respect to the browser, making it safe to automate potentially malicious pages.
  • Stability: Puppeteer should not be flaky and should not leak memory.
  • Simplicity: Puppeteer provides a high-level API that’s easy to use, understand, and debug.

Q: Is Puppeteer a replacement for Selenium WebDriver?​

No. Both projects are valuable for very different reasons:

  • Selenium WebDriver focuses on cross-browser automation and provides bindings for multiple languages; Puppeteer is only for JavaScript.
  • Puppeteer focuses on Chromium; its value proposition is richer functionality for Chromium-based browsers.

That said, you can use Puppeteer to run tests against Chromium, e.g. using the community-driven jest-puppeteer or Puppeteer's Angular integration. While this probably shouldn’t be your only testing solution, it does have a few good points compared to WebDriver classic:

  • Puppeteer requires zero setup and comes bundled with the Chrome version it works best with, making it very easy to start with.
  • Puppeteer has event-driven architecture, which removes a lot of potential flakiness. There’s no need for “sleep(1000)” calls in puppeteer scripts.
  • Puppeteer exposes browser contexts, making it possible to efficiently parallelize test execution.
  • Puppeteer shines when it comes to debugging: flip the “headless” bit to false, add “slowMo”, and you’ll see what the browser is doing. You can even open Chrome DevTools to inspect the test environment.

Q: Why doesn’t Puppeteer v.XXX work with Chromium v.YYY?​

We see Puppeteer as an indivisible entity with Chromium. Each version of Puppeteer bundles a specific version of Chromium – the only version it is guaranteed to work with.

This is not an artificial constraint: A lot of work on Puppeteer is actually taking place in the Chromium repository. Here’s a typical story:

Q: Which Chrome version does Puppeteer use?​

Look for the chrome entry in revisions.ts.

Q: Which Firefox version does Puppeteer use?​

Since Firefox support is experimental, Puppeteer downloads the latest Firefox Nightly when the PUPPETEER_PRODUCT environment variable is set to firefox. That's also why the value of firefox in revisions.ts is latest -- Puppeteer isn't tied to a particular Firefox version.

To fetch Firefox Nightly as part of Puppeteer installation:

PUPPETEER_PRODUCT=firefox npm i puppeteer

To download Firefox Nightly into an existing Puppeteer project:

npx puppeteer browsers install firefox

Q: What’s considered a “Navigation”?​

From Puppeteer’s standpoint, “navigation” is anything that changes a page’s URL. Aside from regular navigation where the browser hits the network to fetch a new document from the web server, this includes anchor navigations and History API usage.

With this definition of “navigation,” Puppeteer works seamlessly with single-page applications.

Q: What’s the difference between a “trusted" and "untrusted" input event?​

In browsers, input events could be divided into two big groups: trusted vs. untrusted.

  • Trusted events: events generated by users interacting with the page, e.g. using a mouse or keyboard.
  • Untrusted event: events generated by Web APIs, e.g. document.createEvent or element.click() methods.

Websites can distinguish between these two groups:

  • using an Event.isTrusted event flag
  • sniffing for accompanying events. For example, every trusted 'click' event is preceded by 'mousedown' and 'mouseup' events.

For automation purposes it’s important to generate trusted events. All input events generated with Puppeteer are trusted and fire proper accompanying events. If, for some reason, one needs an untrusted event, it’s always possible to hop into a page context with page.evaluate and generate a fake event:

await page.evaluate(() => {
  document.querySelector('button[type=submit]').click();
});

Q: Does Puppeteer support media and audio playback?​

Puppeteer uses Chrome for Testing binaries by default which ship with properietary codecs support starting from M120.

Q: I am having trouble installing / running Puppeteer in my test environment. Where should I look for help?​

We have a troubleshooting guide for various operating systems that lists the required dependencies.

Q: I have more questions! Where do I ask?​

There are many ways to get help on Puppeteer:

Make sure to search these channels before posting your question.