Sauce Headless Testing in the Cross-Browser Cloud

Sauce Headless is a container-based, lightweight, and scalable infrastructure solution for testing web apps on headless Chrome and Firefox browsers in our virtual device cloud. Test early in your development cycle on headless browsers to get fast pass/fail data on early pipeline component tests, sanity checks, and pull request tests.

There are a few key differences between setting up Sauce Headless tests versus setting up other Sauce Labs automated web app tests, as described below.

What You'll Need#


The latest version of Sauce Connect Proxy, if you're using it to run Headless tests.

NOTE: At this time, data from tests run in Headless mode is not available to the Sauce Insights analytics features.

Setup and Configuration#

Sauce Headless provides headless Chrome and Firefox in the three most recent versions and the most recent version of Linux. 

WebDriver Capabilities#

You'll need to set desired capabilities in your test that are specific to headless testing, as shown in this example:

saucelabs_headless_chrome": {
"request_timeout_options": {
"timeout": 900000
"globals": {
"waitForConditionTimeout": 60000,
"waitForConditionPollInterval": 100
"use_ssl": true,
"selenium_port": 443,
"selenium_host": "",
"desiredCapabilities": {
"browserName": "chrome",
"version": "latest-2",
"platform": "Linux",
"javascriptEnabled": true

Language Bindings#

You can run Sauce Headless tests in a variety of programming languages and test frameworks. Here are some samples:

TestNG Example

  1. Head to Sauce Labs Training: Java Headless Example Scripts on GitHub and review the page to ensure you have the prerequisite software.
  2. Download or clone this sample script from the repo.
  3. Resolve dependencies with Maven:
$ mvn dependency:resolve
  1. Export your Sauce Labs username and access key:
export SAUCE_USERNAME=my-sauce-username
export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2cy8f4
  1. Run the following commands:
$ cd headless/
$ mvn clean test -Dtest=SampleHeadlessSauceTest
  1. Confirm that you can see the following output (or something similar) in the console:
Running SampleHeadlessSauceTest
Configuring TestNG with: org.apache.maven.surefire.testng.conf.TestNG652Configurator@1ff8b8f
May 31, 2019 11:46:23 AM org.openqa.selenium.remote.ProtocolHandshake createSession
INFO: Detected dialect: W3C
title of page is: Swag Labs
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 15.082 sec
Results :
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 17.308 s

Additional resources: Sauce Labs Java Demonstration Scripts.

Data Center Endpoints for Headless#

The containers used for Sauce Headless testing are hosted in the Sauce Labs East Coast data center, which is entirely separate from our data centers in the West Coast and in the EU. You'll need to connect to the US-East Data Center to access the web UI, Selenium endpoint, and Sauce Connect Proxy endpoint for headless testing.

The US-East IP addresses should be reachable from your network. If there's an issue, see the Whitelisting for Restricted Networks section of System and Network Requirements for Sauce Connect Proxy.

NOTE: Cross-Browser VMs are not available at this time in US-East.

Using the Sauce Headless Web UI#

Information about your Headless testing jobs is accessible by logging into the headless testing web interface.

If you want to use a Sauce Connect Proxy tunnel for your Sauce Headless tests, you'll need to start it from here in the UI.

Headless Testing with Sauce Connect Proxy#

If you're testing website that's on your local machine or behind a corporate firewall, we recommend using Sauce Connect Proxy.

To use Sauce Connect Proxy in conjunction with your Sauce Headless tests, be sure you have the latest version on your machine. You'll need to start a new, separate tunnel from the one used for the Virtual and Real Device Cloud, by connecting to the Sauce Headless-specific endpoint.

Video Tutorial: Running Headless Tests#

This video shows you how to configure your early pipeline tests to run in Sauce Headless and determine which of your tests might be a good candidate for this lightweight and cost-effective testing solution.

Last updated on by kimsaucelabs