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.

See the following sections for more information:

What You'll Need

If you plan to run Headless tests in conjunction with Sauce Connect Proxy, we strongly recommend using the latest version of Sauce Connect Proxy.

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

Setting Up Headless Testing on Sauce Labs

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

WebDriver Capabilities

Set the desired capabilities in your test to use 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": "us-east1.headless.saucelabs.com",
      "desiredCapabilities": {
        "browserName": "chrome",
        "version": "latest-2",
        "platform": "Linux",
        "javascriptEnabled": true
      }
    },

Language Bindings

Select a desired programming language and test framework to see working samples of headless tests running on Sauce Labs. 

Test Frameworks

TestNG Example Walkthrough

  1. Download or clone the sample script from GitHub.

  2. Ensure you have the prerequisite software.

  3. Resolve dependencies with Maven:

    $ mvn dependency:resolve
  4. Export your Sauce Labs Username and Access Key:

    export SAUCE_USERNAME=my-sauce-username
    export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2cy8f4
  5. Run the following command:

    $ cd headless/
    $ mvn clean test -Dtest=SampleHeadlessSauceTest

    You should see the following output (or something similar) in the console:

    -------------------------------------------------------
     T E S T S
    -------------------------------------------------------
    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] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time:  17.308 s

Pytest Example Walkthrough

  1. Download or clone the sample script from GitHub.

  2. Ensure you have the prerequisite software.

  3. Install the following modules:

    pip install pytest pytest-xdist
  4. Export your Sauce Labs Username and Access Key:

    export SAUCE_USERNAME=my-sauce-username
    export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2cy8f4
  5. Run the following command:

    pytest -n8 test_demo.py

    You should see the following output (or something similar) in the console:

    platform darwin -- Python 3.7.1, pytest-4.4.0, py-1.7.0, pluggy-0.12.0
    rootdir: /path/to/python/headless-examples
    plugins: forked-1.0.2, xdist-1.28.0
    gw0 [4] / gw1 [4] / gw2 [4] / gw3 [4] / gw4 [4] / gw5 [4] / gw6 [4] / gw7 [4]
    ....                                                                    

WebdriverIO Example Walkthrough

  1. Download or clone the sample script from GitHub.

  2. Ensure you have the prerequisite software.

  3. Navigate to the headless-examples directory and install node package dependencies:

    $ cd headless-examples/
    $ npm install
  4. Export your Sauce Labs Username and Access Key:

    export SAUCE_USERNAME=my-sauce-username
    export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2cy8f4
  5. Run the following command:

    $ npm test test/headless-chrome-test.js

    You should see the following output (or something similar) in the console:

     mocha "test/headless-chrome-test.js"
    
    
    
      headless chrome test
    Page Title is: Swag Labs
        ✓ get-title-test (2594ms)
    
    
      1 passing (13s)                                                              


More examples: Sauce Labs Training on GitHub: Ruby examples.

Rspec Example Walkthrough

  1. Setup Gemfile.

    • Install bundler so that we can easily update and resolve dependencies:

      $ gem install bundler
      
      
  2. Execute the bundle Command.

    • Use the following to install the required gems:

      $ bundle install --path .bundle
  3. Run the Test Scripts.

NUnit Example Walkthrough

Refer to the instructions at Sauce Labs Training on GitHub: C# demo scripts.

Data Center Endpoints for Sauce 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.

Sauce Connect Proxy for Headless Testing

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

To use it 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 (see Data Center Endpoints).

Video Tutorial: Running Headless Tests

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