---
title: Puppeteer Testing in the Cloud | TestingBot
description: 'Run Puppeteer tests on the TestingBot cloud grid: Chrome, Microsoft
  Edge and Firefox. Parallel execution, video, browser logs and tunnel support. Free
  trial.'
source_url:
  html: https://testingbot.com/support/web-automate/puppeteer
  md: https://testingbot.com/support/web-automate/puppeteer/index.md
---
# Puppeteer Testing

[Puppeteer](https://pptr.dev/) 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.

See our [Example Puppeteer Repository](https://github.com/testingbot/puppeteer-testingbot-example) for some examples on how to run Puppeteer tests on TestingBot.

## 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 only want to use the TestingBot 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:

[Chrome](https://testingbot.com#)[Edge](https://testingbot.com#)[Firefox](https://testingbot.com#)

    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' })
    await browser.close()

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

    const puppeteer = require('puppeteer-core')
    
    const capabilities = {
        'tb:options': {
            key: process.env.TB_KEY,
            secret: process.env.TB_SECRET
        },
        browserName: 'edge',
        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' })
    await browser.close()

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

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

    const browser = await puppeteer.launch()

### After

    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.

  ![OS selected](https://testingbot.com/assets/environments/svg/windows11-0e1b28bc0fdd5034d3e4d3dc8d346c500a8c6522facf4b45d0da56537c1f1c6d.svg) Windows 11 › ![Browser selected](https://testingbot.com/assets/environments/svg/chrome-c4081ff447d2d898d4afcb8f074a907c960e6f007716c1a1d119eee6803c4042.svg) Chrome 139 

Loading environments...

Please wait while we load the available browsers and platforms.

    

## 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](https://testingbot.com/support/web-automate/puppeteer/options#name), [extra (metadata) information](https://testingbot.com/support/web-automate/puppeteer/options#customdata) or group tests together as a [build](https://testingbot.com/support/web-automate/puppeteer/options#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.

    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=WIN11'
        })
        const page = await browser.newPage()
    
        await page.goto('https://testingbot.com/')
        const title = await page.title()
    
        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](https://testingbot.com/support/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 capabilities = {
        'tb:options': {
            key: process.env.TB_KEY,
            secret: process.env.TB_SECRET
        },
        browserName: 'chrome',
        browserVersion: 'latest',
        tunnelIdentifier: 'myPuppeteerTunnel'
    }
    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' })
    await 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](https://github.com/testingbot/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 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' })
      await browser.close()
      await new Promise((resolve, reject) => {
        tunnel.close((err) => {
          if (err) {
            reject(err)
            return
          }
          resolve()
        })
      })
    })()

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 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))}`,
      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' })
    await browser.close()

## Puppeteer Framework examples

- [CodeceptJS](https://testingbot.com/support/web-automate/puppeteer/codeceptjs)

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

- [Jest](https://testingbot.com/support/web-automate/puppeteer/jest)

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

- [Chromedp](https://testingbot.com/support/web-automate/puppeteer/chromedp)

`chromedp` is a Golang framework to use with Puppeteer.

- [PyTest](https://testingbot.com/support/web-automate/puppeteer/pytest)

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

- [WebdriverIO](https://testingbot.com/support/web-automate/puppeteer/webdriverio)

`WebdriverIO` is an Automation Test Framework for Node.js.

Was this page helpful? Yes No 

## Looking for More Help?

Have questions or need more information?   
 You can reach us via the following channels:

- [Email us](https://testingbot.com/contact/new)
- [Join our Slack Channel](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)