A guide on how to run automated tests with Puppeteer

  • Share on Facebook
  • Share on Twitter
  • Share on LinkedIn
  • Share on HackerNews

So you are wondering if using Puppeteer for your automated browser testing is a good idea?
The short answer is: yes, it's fast, robust and offers a clean syntax to write readable tests.
To find out more about running UI tests with Puppeteer, please continue reading this tutorial.

What is Puppeteer?

Puppeteer is a NodeJS framework which provides an easy to use API to interact with Chrome or Chromium browsers over the DevTools protocol.

By default, Puppeteer is configured to run headless (no visible UI), but it can run in headful mode as well (where you see the UI of the browser).

Wondering what can Puppeteer do? Here's a short overview of some of its features:

  • Test a SPA (Single-Page application)
  • Automate any action in the browser, similar to Selenium
  • Generate pixel-perfect PDFs from webpages
  • Very fast testing through the DevTools protocol
  • Capture a Timeline Trace of your site, to diagnose performance issues
  • Integrates with other test frameworks such as Jest, CodeceptJS, WebDriverIO and others

Cross Browser Testing with Puppeteer

With Puppeteer you can test your website on all chromium based browsers, including Chrome, Microsoft Edge Chrome and Chromium.

These browsers are used by a large number of users, it's important to make sure your website behaves correctly on these browsers.

You can test various versions of each browser, going from the latest browser all the way to the oldest supported version by Puppeteer.

Right now, Safari (WebKit), Firefox and IE are not yet supported. As Puppeteer only communicates through the DevTools protocol, only browsers implementing this protocol are supported.
If you are looking to test on other browsers, we suggest using Selenium WebDriver. This supports all major browser vendors, including mobile browsers.

What is Puppeteer Recorder?

Puppeteer Recorder is a built-in feature in Chrome which allows you to record your actions as a Puppeteer script.
Currently it's available as a Chrome DevTools experiment, which you can enable by checking the Recorder checkbox under Settings > Experiments in your Chrome Devtools.

Using the Puppeteer recorder is easy and it's a great way to quickly generate Puppeteer scripts, which you can then configure to run automated flows on your own browser or on a cloud based grid such as TestingBot.

To find out more about enabling the Puppeteer Recorder, and how to use it, please see our Puppeteer Recorder documentation.

Using Puppeteer with Jest

Jest is a Javascript Testing Framework, created by Facebook, which provides easy testing for several javascript projects, including Babel, TypeScript, React, Angular, Vue and other projects.

If your app is using NestJS or GraphQL, or any other popular Javascript framework, then you can start using Jest.

It is fast to install and use, provides a feature-rich API, offers easy test mocking and snapshot functionality. Jest is able to run your tests in parallel, offers great error reporting and isolated test runs.

There's a project called Jest Puppeteer, which allows QA and developers to run tests created for Jest with Puppeteer. It offers an easy way to run your tests with Puppeteer and provides specific matchers, tailored to Puppeteer, called expect-puppeteer.
The project provides a Jest preset, called jest-puppeteer which you can add in your Jest configuration file (jest.config.js).

Once added, you can run your Jest tests with Puppeteer, like this example:

import 'expect-puppeteer'
describe('Google', () => {
  beforeAll(async () => {
    await page.goto('https://testingbot.com')

  it('should display "testingbot" text on page', async () => {
    await expect(page).toMatch('testingbot')

Cloud testing with Jest and Puppeteer

To install and use Jest with Puppeteer in a cloud environment, please see our Jest and Puppeteer documentation, where we guide you to run your tests on the TestingBot browser grid.

How to use PyTest with Puppeteer?

If you are looking to run automated Python tests with PyTest and Puppeteer, then we suggest looking into pytest pyppeteer.

The Pyppeteer project allows you to run your Puppeteer tests with Python syntax. It supports asynchronous (async) Python tests with pytest-asyncio.

Please see the simple example below, where we are using Puppeteer and Python + PyTest:

import pytest
import pyppeteer

async def test_title():
    browser = await pyppeteer.connect(browserWSEndpoint='wss://cloud.testingbot.com?key=key&secret=secret&browserName=chrome&browserVersion=latest')
    page = await browser.newPage()
    await page.goto('https://testingbot.com')
    title = await page.title()
    assert title == 'Cross Browser Testing and Mobile App Testing | TestingBot'
    await browser.close()
  except E:

This example will open a new browser with Puppeteer, navigate to the TestingBot homepage and verify if the title is correct.

Running tests with WebDriverIO and Puppeteer

WebDriverIO is a popular test automation framework with built-int support for both Selenium WebDriver and Puppeteer (Chrome DevTools protocol).

WebDriverIO has a large number of community plugins to extend its functionalities, it can test modern web applications such as websites written in React, Vue, Angular, Svelte or other frontend frameworks.

Mobile testing is supported as well, though with Puppeteer this is not yet an option, since Puppeteer only works with Desktop browsers at the moment of writing this article.

To get started, simply install WebDriverIO and try this sample Puppeteer example with WebDriverIO:

import { format } from 'util'
import { remote } from 'webdriverio'

(async () => {
    const browser = await remote({
        capabilities: {
            'wdio:devtoolsOptions': {
                browserWSEndpoint: format(

    await browser.url('https://testingbot.com')

    const title = await browser.getTitle()
    console.log(title) // returns "Cross Browser Testing and Mobile App Testing | TestingBot"

    await browser.deleteSession()

Testing with Puppeteer and CodeceptJS

CodeceptJS is a popular end-to-end testing framework built for NodeJS, it is driver agnostic and supports Selenium, Playwright, Appium, TestCafe and Puppeteer. It supports PageObjects, scenario-driven tests and extensive reporting.

Setting up CodeceptJS is straightforward, simply follow the QuickStart guide on their website and configure the Puppeteer helper in codecept.conf.js with the correct browserWSEndpoint.

exports.config = {
  tests: './*_test.js',
  output: './output',
  helpers: {
    Puppeteer: {
      url: 'https://github.com',
      show: true,
      windowSize: '1200x900',
      chrome: {
        browserWSEndpoint: "wss://cloud.testingbot.com?key=[key]&secret=[secret]"
  include: {
    I: './steps_file.js'
  bootstrap: null,
  mocha: {},
  name: 'codecept',
  plugins: {
    retryFailedStep: {
      enabled: true
    screenshotOnFail: {
      enabled: true

Once configured, you can create and run your first basic CodeceptJS test via Puppeteer:

Feature('My First Test');

Scenario('test something', (I) => {

To run the example, please execute npx codeceptjs run --steps in your terminal.

Generating HAR files with Puppeteer

HAR files are JSON files, often used to diagnose performance problems with websites.
The files contain all information related to the HTTP (s)requests made, including headers, responses, status codes and other data.

When running automated tests, you might want to generate and store HAR files during your tests.
With Puppeteer, this is possible by using the puppeteer-har package.

Once you've generated a HAR file, you can easily inspect the details of the HAR file with any of the available HAR viewers that you can find online.
Most HAR viewers will display a waterfall-like visualization of the network requests, similar to how Chrome Devtools or Firefox shows these requests.

After you've installed puppeteer-har package, you can start using it in your Puppeteer scripts.

const puppeteer = require('puppeteer');
const PuppeteerHar = require('puppeteer-har');
(async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'wss://cloud.testingbot.com?key=[key]&secret=[secret]'
  const page = await browser.newPage();
  const har = new PuppeteerHar(page);
  await har.start({ path: 'results.har' });
  await page.goto('https://testingbot.com');
  await har.stop();
  await browser.close();

Once the Puppeteer test has finished running, a results.har file will be generated.

  • Share on Facebook
  • Share on Twitter
  • Share on LinkedIn
  • Share on HackerNews
TestingBot Logo

Sign up for a Free Trial

Start testing your apps with TestingBot.

No credit card required.

Other Articles

Tutorial on debugging Cypress tests

This article will focus on how to debug your Cypress tests with Cypress debugger and other developer tools.

Read more
Working with cookies - Selenium WebDriver

Handling cookies with Selenium WebDriver is a common task, since most websites use cookies. In this guide, we'll show you how to do this with Selenium.

Read more
How to use the Actions Class In Selenium

Selenium WebDriver comes with an Action Class, which allows you to simulate user input events, such as mouse and keyboard actions.

Read more
Handling Captcha during Automated Testing

We will discuss possible solutions to run automated tests with Captcha enabled websites.

Read more
Cypress and Cucumber Browser Testing

Cypress and Cucumber is a great combination to write clean and precise end-to-end browser tests.

Read more
TestNG automation with Selenium

TestNG is a popular Java Test Framework which allows you to write clean Selenium tests with built-in parallelisation.

Read more