Features
Start a free trial

Puppeteer Options

This page lists various options that you can use to customise your Puppeteer sessions on TestingBot.

Basic Settings

Browser Name

The name of the browser to run your Puppeteer test on. TestingBot currently supports these browserNames:.

  • Chrome
  • Edge
  • Firefox
Copy code
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))}`
})
Copy code
const puppeteer = require('puppeteer')
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))}`
})
Copy code
const puppeteer = require('puppeteer')
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))}`
})

Browser Version

The version of the browser to run your Puppeteer test on.

Select a browser & version
Copy code
Other Options:
  • "version": "*" : If you use * as version, TestingBot will pick a random version.
  • "version": "latest" : TestingBot will automatically take the latest version. You can also use latest-1, latest-2, ... to test on the next most recent versions. For example, if the current latest Chrome version is 89 and you use latest-2, then the test will run on Chrome 87.

  • "version": "<=16" : TestingBot will pick a version smaller than or equal to the version you specify with <=.
    "version": "16>=" : TestingBot will pick a version higher than or equal to the version you specify with >=.

Browser Platform

The OS/platform for the test VM which will run the Puppeteer test.

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  },
  platform: 'WIN10'
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})
Possible values:
  • WIN11
  • WIN10
  • SEQUOIA
  • SONOMA
  • VENTURA
  • MONTEREY
  • BIGSUR
  • LINUX

Make a video of your tests

By default we record a video of your test, which is accessible in the member area. If you do not wish to have this, you can disable it with this option.
Video should not slow down your test considerably.

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

Test Privacy

Make the test results for this test public so that everyone can access the results.

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

Blacklist hostnames

The hostnames you specify will be pointed to localhost instead of their real destination. This means you can speed up tests by blocking third party content which you don't need and slows down your test.

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  },
  browserName: 'chrome',
  browserVersion: 'latest',
  blacklist: 'site1.com,site2.com'
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})
Value Type
string (comma-separated)

Customize Logging

By default, TestingBot records logs of all Puppeteer actions.

Set this option to false if you don't want TestingBot to record anything (for example, if you have sensitive data).

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  },
  browserName: 'chrome',
  browserVersion: 'latest',
  recordLogs: true
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})
Value Type Default Value Possible Values:
boolean true true, false

Custom Time Zones

Change the Time Zone of the Virtual Machine to the Time Zone you specify. You can find a list of timezones on Wikipedia. Only location names are supported (not their paths). See some examples below:

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  },
  browserName: 'chrome',
  browserVersion: 'latest',
  timeZone: 'Etc/UTC'
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})
Value Type Default Value Possible Values:
string "Etc/UTC" List of timezones

Change Screen Resolution

Will adjust the screen resolution before your test.

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  },
  browserName: 'chrome',
  browserVersion: 'latest',
  'screen-resolution': '1280x1024'
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})
Value Type Default Value
string "1280x1024"
Platform Resolutions
Windows/Linux
  • 800x600
  • 1024x768
  • 1152x864
  • 1280x768
  • 1280x800
  • 1280x960
  • 1280x1024
  • 1400x1050
  • 1600x1200
  • 1680x1050
  • 1920x1080
  • 1920x1200
  • 2560x1440
macOS
  • 800x600
  • 1024x768
  • 1280x768
  • 1280x800
  • 1280x960
  • 1280x1024
  • 1366x768
  • 1440x900
  • 1600x900
  • 1600x1200
  • 1680x1050
  • 1920x1080
  • 1920x1200
  • 2048x1536

Geolocation Testing

We provide an option where you can specify from which country you'd like to run the test from.

Once you specify this option, the virtual machine we provision for your test will be configured to use a proxy in the country you specified.

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

We currently support the following country codes:

  • '*': this will take a random country from the list below
  • 'AU': Australia
  • 'BH': Bahrain
  • 'BE': Belgium
  • 'BR': Brazil
  • 'CN': China
  • 'FR': France
  • 'DE': Germany
  • 'IN': India
  • 'IT': Italy
  • 'JP': Japan
  • 'SG': Singapore
  • 'ZA': South Africa
  • 'ES': Spain
  • 'SE': Sweden
  • 'AE': United Arab Emirates
  • 'GB': United Kingdom
  • 'US': United States

Upload

This option allows you to upload a file to the test VM running the Puppeteer test.
TestingBot will first download the file from the URL you specified and save it on the test VM so your test can use the file.

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  },
  browserName: 'chrome',
  browserVersion: 'latest',
  upload: 'https://testingbot.com/assets/logo-head.png',
  uploadFilepath: '/tmp/test.png'
}
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:3000')
const elementHandle = await page.$('input[type=file]')
await elementHandle.uploadFile('/tmp/test.png')
await page.click('upload-button')
browser.close()

You need specify the download URL as upload and use uploadFilepath to indicate where TestingBot needs to put the file.

Change Test Name

Add a name to this test, which will show up in our member area and API.

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  },
  browserName: 'chrome',
  browserVersion: 'latest',
  name: 'First Test'
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})
Value Type Default Value
string unnamed test

Group Tests

A key you can use to group certain tests in the same build (for example in Jenkins).
The builds will appear in our member area.

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

Timeout

Controls the timeout setting of a Puppeteer session. This setting, which is specified in seconds, controls when a session times out.

A timeout occurs when a session has not received any commands from your Puppeteer test for the amount of seconds specified (default is 90 seconds).
If a certain Puppeteer command takes longer than the specified setting, the session will automatically close.

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  },
  browserName: 'chrome',
  browserVersion: 'latest',
  timeout: 90
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})
Value Type Default Value
int (specify number of seconds) 90 seconds

Idle Timeout

The maximum amount of time a browser will wait before proceeding to the next step in your test.

A timeout occurs when a session has not received any commands from your Puppeteer test for the xx amount of seconds specified.

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET,
    timeout: 120000
  },
  browserName: 'chrome',
  browserVersion: 'latest'
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})
Value Type Default Value
int (specify number of seconds) 90 seconds

Maximum Test Duration

The maximum duration for a single test. This is a safeguard to prevent bad tests from using up your credits.

We generally recommend to keep tests short (less than 10 minutes). It's better to split up large tests in smaller individual tests.
This keeps your tests fast and allows for more parallelization of your tests.

Copy code
const puppeteer = require('puppeteer')
const capabilities = {
  'tb:options': {
    key: process.env.TB_KEY,
    secret: process.env.TB_SECRET
  },
  browserName: 'chrome',
  browserVersion: 'latest',
  maxDuration: 1800
}
const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com/puppeteer?capabilities=${encodeURIComponent(JSON.stringify(capabilities))}`
})
Value Type Default Value
int (specify number of seconds) 1800 seconds (30 minutes)

Custom Metadata

Send along custom data, for example your release, server, commit hash, ...
This will show up on the test detail page in the TestingBot member area.

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

Startup Flags

You can customize the startup flags of the browser by passing in extra flags.

This is identical to passing args with Puppeteer.

Copy code
const startupFlags = []
startupFlags.push('--window-size=1280,720')
startupFlags.push('--hide-scrollbars')

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.testingbot.com` + 
  `?key=api_key&secret=api_secret&browserName=chrome&startupFlags=${JSON.stringify(startupFlags)}`
})

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

TestingBot Tunnel

You can specify the tunnelIdentifier to use Puppeteer with TestingBot Tunnel.

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: 'myPuppteerTunnel'
}
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:3000')
await page.screenshot({ path: 'screenshot.png' })
browser.close()

By default we support proxying these ports for localhost testing: [443, 80, 8080, 3030, 3000, 3001].
If you need additional ports, please pass an array of port numbers to either localHttpPorts or localHttpsPorts