A guide on how to run automated tests with 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

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.

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.

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')
  })
})

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

@pytest.mark.asyncio
async def test_title():
  try:
    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:
    print(E)

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

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(
                    `wss://cloud.testingbot.com?key=%s&secret=%s&browserName=chrome&browserVersion=latest`,
                    `key`,
                    `secret`
                )
            }
        }
    })

    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()
})()

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) => {
  I.amOnPage('https://testingbot.com');
  I.see('TestingBot');
});

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

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.