Puppeteer Testing

Installing Puppeteer

To install Puppeteer, simply use yarn or npm:

npm i --save puppeteer

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

npm i puppeteer-core

Running your first Puppeteer test

To run your first test, please use this example:

const puppeteer = require('puppeteer')

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://cloud.testingbot.com?key=api_key&secret=api_secret&browserName=chrome&browserVersion=latest'
})

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

const puppeteer = require('puppeteer')

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://cloud.testingbot.com?key=api_key&secret=api_secret&browserName=edge&browserVersion=latest'
})

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

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

const browser = await puppeteer.launch()

After

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://cloud.testingbot.com?key=api_key&secret=api_secret&browserName=chrome&browserVersion=latest'
})

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.

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://cloud.testingbot.com?key=api_key&secret=api_secret&browserName=%browser%&browserVersion=%version%'
})

Select a browser & version
Chrome 89

Chrome 89

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.

You can also fetch the unique identifier for each Puppeteer test (we call it the sessionId), which you can use with our REST API to do various things:

• Update Test status (set Passed or Failed)
• Fetch Test Details which includes logs, artifacts and other meta-data
• and various other operations

To fetch the sessionId in your Puppeteer script, you can parse the sessionId from the browser.userAgent() method.
See the example below, where we run a Puppeteer script, fetch the sessionId at the end of the test and pass it to a NodeJS library which will update the tests' status via our REST API.

const TestingBot = require('testingbot-api');
const tb = new TestingBot({
    api_key: 'api_key',
    api_secret: 'api_secret'
})

const puppeteer = require('puppeteer-core');

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

    const page = await browser.newPage()
    await page.goto('https://testingbot.com')
    const userAgent = await browser.userAgent()
    const sessionId = userAgent.sessionId

    var testData = { "test[success]" : "1", "test[status_message]" : "test" };
    await new Promise((resolve) => tb.updateTest(testData, sessionId, function(error, testDetails) { resolve(testDetails) }))

    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.

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.

const puppeteer = require('puppeteer')

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://cloud.testingbot.com?key=api_key&secret=api_secret&browserName=chrome&browserVersion=latest&tunnelIdentifier=myPuppeteerTunnel',
  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:

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 browser = await puppeteer.connect({
    browserWSEndpoint: 'wss://cloud.testingbot.com?key=api_key&secret=api_secret&browserName=chrome&browserVersion=latest&tunnelIdentifier=puppeteerTunnel'
  })

  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:*"

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:

const puppeteer = require('puppeteer')

const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://cloud.testingbot.com?key=api_key&secret=api_secret&browserName=edge&browserVersion=latest',
  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

• 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.