Skip to main content

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

Enterprise Plans only

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


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 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 Walkthrough

  1. Head to Sauce Labs Training: Java Example Scripts on GitHub and review the README page to ensure you have the prerequisite software.
  2. Copy this headless sample script from our GitHub 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 command:
$ cd headless/
$ mvn clean test -Dtest=SampleHeadlessSauceTest
Click here to see a successful output example
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

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, please refer to the Sauce Connect Proxy documentation > allowlisting section.


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.

Additional Resources