Features
Start a free trial

Puppeteer Testing

Puppeteer is an automation framework which uses the Chrome Devtools protocol to automate a browser.

With Puppeteer, you can control a headless (or headful) browser through the Devtools protocol. Compared to Selenium, this might be faster when running automated tests.

Please see the documentation below on how to run Puppeteer tests on Chrome, Microsoft Edge and Firefox browsers in the TestingBot cloud.

Installing Puppeteer

To install Puppeteer, simply use yarn or npm:

Copy code
npm i --save puppeteer

By default, installing Puppeteer will also install a Chromium build.
If you only want to use the TestingBot cloud, you might consider installing Puppeteer without the bundled Chromium build, called puppeteer-core:

Copy code
npm i puppeteer-core

Running your first Puppeteer test

To run your first test, please use this example:

Copy code
const puppeteer = require('puppeteer-core')
const capabilities = {
    'tb:options': {
        key: process.env.TB_KEY,
        secret: process.env.TB_SECRET
    },
    browserName: 'chrome',
    browserVersion: 'latest'
}

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})

const page = await browser.newPage()
await page.goto('https://testingbot.com')
await page.screenshot({ path: 'screenshot.png' })
browser.close()

This example will start a Chrome Browser, navigate to TestingBot.com and save a PNG screenshot of the homepage.

Copy code
const puppeteer = require('puppeteer-core')

const capabilities = {
    'tb:options': {
        key: process.env.TB_KEY,
        secret: process.env.TB_SECRET
    },
    browserName: 'chrome',
    browserVersion: 'latest'
}

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})

const page = await browser.newPage()
await page.goto('https://testingbot.com')
await page.screenshot({ path: 'screenshot.png' })
browser.close()

This example will start a Microsoft Edge Browser, navigate to TestingBot.com and save a PNG screenshot of the homepage.

Copy code
const puppeteer = require('puppeteer-core')

const capabilities = {
    'tb:options': {
        key: process.env.TB_KEY,
        secret: process.env.TB_SECRET
    },
    browserName: 'firefox',
    browserVersion: 'latest'
}

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})

const page = await browser.newPage()
await page.goto('https://testingbot.com')
await page.screenshot({ path: 'screenshot.png' })
browser.close()

This example will start a Firefox Browser, navigate to TestingBot.com and save a PNG screenshot of the homepage.

Updating your existing Puppeteer scripts

With a Puppeteer test, you'll usually start a browser with await puppeteer.launch()

To start using our service, simply replace this line with our browser endpoint:

Before

Copy code
const browser = await puppeteer.launch()

After

Copy code
const capabilities = {
    'tb:options': {
        key: process.env.TB_KEY,
        secret: process.env.TB_SECRET
    },
    browserName: 'chrome',
    browserVersion: 'latest'
}

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})

Specifying browser and version

To specify on which browser and version your Puppeteer test should run, you can include both a browserName and browserVersion in the browserWSEndpoint URL.

Select a browser & version
Copy code

Updating Test Details

Every Puppeteer test will appear in the TestingBot dashboard, by default as an unnamed test.
You can specify various parameters in the browserWSEndpoint to customize this.
Specify a name, extra (metadata) information or group tests together as a build.

TestingBot has created a custom Puppeteer command, which you can use in your tests, to mark a test as passed or failed in the TestingBot dashboard.

See the example below, where we run a Puppeteer script and depending on whether the test passes or fails, we send back the correct test status to TestingBot.

Copy code
const puppeteer = require('puppeteer-core')
const expect = require('chai').expect

(async () => {
    const browser = await puppeteer.connect({
        browserWSEndpoint: 'wss://cloud.testingbot.com?key=api_key&secret=api_secret&browserName=chrome&browserVersion=latest&platform=WIN10'
    })
    const context = await browser.newContext()
    const page = await context.newPage()

    await page.goto('https://testingbot.com/')

    try {
        expect(title).to.equal("Cross Browser Testing and Mobile App Testing. Test on web browsers, mobile emulators, simulators and physical mobile devices.", 'Expected page title is incorrect!')
        // This is ok, so mark the test as passed
        await page.evaluate(_ => {}, `testingbot_executor: ${JSON.stringify({action: 'setSessionStatus',arguments: {passed: true, reason: 'Title matched'}})}`)
      } catch {
        // Test failed, mark the test as failed on TestingBot
        await page.evaluate(_ => {}, `testingbot_executor: ${JSON.stringify({action: 'setSessionStatus',arguments: {passed: false, reason: 'Title did not match'}})}`)
      }
    await browser.close()
})()

Puppeteer and TestingBot Tunnel

Using Puppeteer in combination with TestingBot Tunnel allows you to test websites behind a firewall or on your local machine with Puppeteer on TestingBot.

Setup Tunnel

To use TestingBot Tunnel in combination with Puppeteer, you first need to start the TestingBot Tunnel and pass it a tunnelIdentifier name of your liking.

Copy code
java -jar testingbot-tunnel.jar key secret -i myPuppeteerTunnel

In this example, we'll start a TestingBot Tunnel with identifier myPuppeteerTunnel.
Next, we'll need to configure our Puppeteer script to use the tunnel, using the same identifier.

Setup Puppeteer

To let Puppeteer know which tunnel we want to use, we need to specify the identifier from before as a parameter.
Please see the example below where we pass the tunnelIdentifier with myPuppeteerTunnel.

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
    'tb:options': {
        key: process.env.TB_KEY,
        secret: process.env.TB_SECRET
    },
    browserName: 'chrome',
    browserVersion: 'latest',
    tunnelIdentifier: 'puppeteerTunnel'
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`,
  headless: false
})

const page = await browser.newPage()
await page.goto('http://localhost:3000')
await page.screenshot({ path: 'screenshot.png' })
browser.close()

This Puppeteer script will open the latest Chrome browser on the TestingBot browser grid, use the tunnel to access your localhost website and take a screenshot from that page.

Puppeteer and TestingBot Tunnel Launcher

testingbot-tunnel-launcher is a NodeJS library which allows you to manage the tunnel from within your NodeJS script.

To use it, you can install with npm install testingbot-tunnel-launcher and use it with Puppeteer:

Copy code
const testingbotTunnel = require('testingbot-tunnel-launcher')
const puppeteer = require('puppeteer-core')

(async () => {
  const tunnel = await new Promise((resolve, reject) => {
    testingbotTunnel({
      apiKey: 'api_key',
      apiSecret: 'api_secret',
      verbose: true,
      tunnelIdentifier: 'puppeteerTunnel'
    }, function (err, tunnel) {
      if (err) {
        reject(err)
        return
      }
      resolve(tunnel)
    })
  })

  const capabilities = {
    'tb:options': {
        key: process.env.TB_KEY,
        secret: process.env.TB_SECRET
    },
    browserName: 'chrome',
    browserVersion: 'latest',
    tunnelIdentifier: 'puppeteerTunnel'
  }
  const browser = await puppeteer.connect({
    browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
  })

  const page = await browser.newPage()
  await page.goto('http://localhost:8080')
  await page.screenshot({ path: 'screenshot.png' })
  browser.close()
  tunnel.close()
})()

This example will start a new Tunnel, start a Puppeteer script on the latest Chrome version in TestingBot, and take a screenshot of the website running on your local computer (http://localhost:8080)

Debugging Tips

Below are some tips on how to debug your Puppeteer scripts.

Verbose Logging

To see logs of what Puppeteer is sending and receiving, you can use this environment variable: env DEBUG="puppeteer:*"

Copy code
DEBUG="puppeteer:*" node puppeteer.js

Slow Motion option

With the slowMo option you can slow down each operation during the Puppeteer session.
To see the result, please specify these options:

Copy code
const puppeteer = require('puppeteer')

const capabilities = {
    'tb:options': {
        key: process.env.TB_KEY,
        secret: process.env.TB_SECRET
    },
    browserName: 'chrome',
    browserVersion: 'latest',
    tunnelIdentifier: 'puppeteerTunnel'
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`,
  headless: false,
  slowMo: 250 // slow down by 250ms
})

const page = await browser.newPage()
await page.goto('https://testingbot.com')
await page.screenshot({ path: 'screenshot.png' })
browser.close()

Puppeteer Framework examples

  • CodeceptJS

    CodeceptJS is an end-to-end test framework capable of running Puppeteer tests.

  • Jest

    Jest-Puppeteer allows you to run tests with Jest on browsers controlled with Puppeteer.

  • Chromedp

    chromedp is a Golang framework to use with Puppeteer.

  • PyTest

    pytest-pyppeteer is a Python framework to use with Puppeteer.

  • WebdriverIO

    WebdriverIO is an Automation Test Framework for Node.js.