Options


Below you will find an overview of all the options you can use to customize your headless tests.

Change Browser

Currently HeadlessTesting supports Chrome, Microsoft Edge and Firefox. We are working on adding more browsers.

To change between browsers, simply change the browserWSEndpoint (or wsEndpoint for Playwright) address.

  • Chrome:
    browserWSEndpoint: 'wss://chrome.headlesstesting.com?token=[YOUR-TOKEN]'
  • Edge:
    browserWSEndpoint: 'wss://edge.headlesstesting.com?token=[YOUR-TOKEN]'
  • Firefox:
    browserWSEndpoint: 'wss://firefox.headlesstesting.com?token=[YOUR-TOKEN]'

Change Browser Version

To change the browser version, use the browserVersion=... option.
Make sure the browser version you specify is compatible with the Puppeteer/Playwright version you are using.


const browser = await puppeteer.connect({
  browserWSEndpoint: 'wss://chrome.headlesstesting.com?token=[YOUR-TOKEN]&browserVersion=79'
})

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

Browser Possible versions
chrome dev, 83, 81, 80, 79
edge 81, 80, 79
firefox dev

If you change the browser version, it is important to make sure your Puppeteer/Playwright version is compatible.

For Puppeteer, you can install a version that is compatible with the browser version you need:


npm install puppeteer-core@chrome-{xx} where xx is the version you want to use.

Change Browser Startup Flags

It is possible to pass extra browser flags which we will use to start the browser.
Chrome supports a lot of different startup flags.


Please pass these flags as a JSON encoded string


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

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://chrome.headlesstesting.com` + 
  `?token=[YOUR-TOKEN]&startupFlags=${JSON.stringify(startupFlags)}`
})

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

Change Test Name

We list every test you run in our member dashboard.
By default we'll assign a random name, if you want to specify your own, use this option.


const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://chrome.headlesstesting.com` + 
  `?token=[YOUR-TOKEN]&name=myTest`
})

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

Screen Recorder

Your tests run on headless browsers, so by default the UI of the browser is not visible for screen recording.
Specifying this option will run your test in non-headless mode and will record a video of your test, which will be available in our member dashboard and via our REST API.


const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://chrome.headlesstesting.com` + 
  `?token=[YOUR-TOKEN]&screenRecorder=true`
})

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

Change Timeout

This setting infuences how long we will wait for a new command to arrive from your Puppeteer/Playwright scripts until we decide the connection has timed out.


The default value is 90 seconds for a new command to arrive.
This prevents issues where your script is waiting endlessly, or where you forgot to close your session (browser.close()).


This value should be at least 5 and less than 300.


const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://chrome.headlesstesting.com` + 
  `?token=[YOUR-TOKEN]&timeout=120`
})

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

Change Max Duration

This option changes how long we will allow your session to be open, regardless of any timeout settings.


The default value is 300 seconds. Which means your sessions can not take longer than 300 seconds.


This value should be at least 5 and less than 3000.


const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://chrome.headlesstesting.com` + 
  `?token=[YOUR-TOKEN]&maxduration=120`
})

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

Change Geolocation

If you specify this option, your session will run from a different geolocation.
By default, the browser session originates from Belgium.


To change this, please supply one of the following country codes:


  • 'BE': Belgium
  • 'CN': China
  • 'FR': France
  • 'DE': Germany
  • 'IT': Italy
  • 'JP': Japan
  • 'ES': Spain
  • 'US': United States

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://chrome.headlesstesting.com` + 
  `?token=[YOUR-TOKEN]&geoCountryCode=US`
})

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