Skip to end of metadata
Go to start of metadata

With Sauce Labs you can run automated tests of your web apps against a wide variety of device/operating system/browser combinations.  This topic covers the basic information and example code you need to get your Java tests up and running on Sauce. 

Example Only

The code in this topic is presented as an example only, since your tests and testing environments may require specialized scripting. This information should be taken only as an illustration of how you could set up your tests with Sauce Labs, and is not directly supported by Sauce.


Before getting started, you should review the Best Practices for Running Tests.

You need to have these components installed to set up testing on Sauce with Java. 

  • You must have JDK 1.6  or higher installed
  • You need to have the selenium-java client for your operating system installed. You can download it from, under the section Selenium Client & WebDriver Language Bindings.
  • You should install the Java Helper Library, which will automatically update your Sauce Labs dashboard with information like whether tests have passed or failed, output the Sauce Session ID to stdout for parsing by the Sauce Jenkins and Bamboo plugins, and which provides a com.saucelabs.common.SauceOnDemandAuthentication class, which handles obtaining the Sauce OnDemand user name and access key from environment variables or the filesystem.

Quick Start

Configuring your existing Java-based Selenium tests to run on Sauce Labs is simple. The basic change is just to switch from using a local Selenium driver, to using a remote driver pointed at, specifying your Sauce Labs account credentials and desired browser configuration.
Local Testing Java Example
WebDriver driver = new FirefoxDriver(); 
Java Testing on Sauce Labs Example
DesiredCapabilities caps = DesiredCapabilities.firefox();
caps.setCapability("platform", "Windows 7");
caps.setCapability("version", "38.0");
WebDriver driver = new RemoteWebDriver(new URL(""),

Code Sample

This Java example script executes a simple test to open a browser, navigate to the Sauce Labs demo web app, and then close the browser. It also incorporate a number of best practices, such as using environment variables for authentication credentials, and is set up to report Pass/Fail results to your Sauce Labs dashboard. You can clone this script directly from the saucelabs-training GitHub repo and modify it as you want to test your authentication credentials, set desired capabilities, and run tests against your own web app. 

 Click here to expand...

import org.junit.jupiter.api.*;

import org.openqa.selenium.JavascriptExecutor;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.util.Arrays;
import java.util.List;

import static org.junit.jupiter.api.Assertions.*;

public class InstantSauceJunitTest4 {
    private WebDriver driver;

    public void shouldOpenChrome(TestInfo testInfo) throws MalformedURLException {
        /** Here we set environment variables from your local machine, or IntelliJ run configuration,
         *  and store these values in the variables below. Doing this is a best practice in terms of test execution
         *  and security. If you're not sure how to use env variables, refer to this guide -
         * or check */
        String sauceUserName = System.getenv("SAUCE_USERNAME");
        String sauceAccessKey = System.getenv("SAUCE_ACCESS_KEY");
        String sauceURL = System.getenv("SAUCE_URL");
         * * Here we set DesiredCapabilities, in this exercise we set additional capabilities below that align with
         * * testing best practices such as timeouts, tags, and build numbers
         * */
        DesiredCapabilities capabilities = new DesiredCapabilities();
        capabilities.setCapability("username", sauceUserName);
        capabilities.setCapability("accessKey", sauceAccessKey);
        capabilities.setCapability("browserName", "Chrome");
        capabilities.setCapability("platform", "Windows 10");
        capabilities.setCapability("version", "59.0");
        capabilities.setCapability("name", testInfo.getDisplayName());

        /** Tags are an excellent way to control and filter your test automation
         * in Sauce Analytics. Get a better view into your test automation.
        List<String> tags = Arrays.asList("sauceDemo", "demoTest", "module4", "javaTest");
        capabilities.setCapability("tags", tags);
        /** Another of the most important things that you can do to get started
         * is to set timeout capabilities for Sauce based on your organizations needs. For example:
         * How long is the whole test allowed to run?*/
        capabilities.setCapability("maxDuration", 3600);
        /** A Selenium crash might cause a session to hang indefinitely.
         * Below is the max time allowed to wait for a Selenium command*/
        capabilities.setCapability("commandTimeout", 600);
        /** How long can the browser wait for a new command */
        capabilities.setCapability("idleTimeout", 1000);

        /** Setting a build name is one of the most fundamental pieces of running
         * successful test automation. Builds will gather all of your tests into a single
         * 'test suite' that you can analyze for results.
         * It's a best practice to always group your tests into builds. */
        capabilities.setCapability("build", "SauceDemo");

        /** If you're accessing the EU data center, use the following endpoint:.
         * */
        driver = new RemoteWebDriver(new URL(sauceURL), capabilities);
        /** Don't forget to enter in your application's URL in place of ''. */

     * Below we are performing 2 critical actions. Quitting the driver and passing
     * the test result to Sauce Labs user interface.
    public void cleanUpAfterTestMethod() {
        ((JavascriptExecutor) driver).executeScript("sauce:job-result=" + (true ? "passed" : "failed"));

Running Local Tests

Developing websites/apps within your local network is secure and efficient. The drawback to this method is that local assets are not publicly-accessible on the Internet, so the browsers/devices in the Sauce Labs cloud can't load and test your app. The solution is to use Sauce ConnectSauce Connect is a proxy server that creates a secure tunnel connection between the Sauce Labs virtual machine that runs your test and your local  network. You can also use Sauce Connect to test applications and websites that are located within your corporate firewall. Sauce Connect is not required to run tests on Sauce Labs, only in situations where the application or website you want to test is not publicly accessible. 

Running Tests in Parallel

Now that you’re running tests on Sauce, you may wonder how you can run your tests faster. One way to increase speed is by running tests in parallel across multiple virtual machines.

You can run your tests in parallel at two levels, and you can run your tests in parallel across multiple browsers. For example, if you have 10 tests and want to run on five browsers, this would be parallelism of five. You can also run tests across browsers and each test in parallel. Using our previous example this would be more like 50 parallel tests. Doing this requires that your tests are written in a way that they do not collide with one another, as described in our Best Practice topics avoiding external test dependencies and avoiding dependencies between tests.

Match Thread Count to Concurrency Limit

You should match your thread count to your concurrency limit, which is shown in the My Account section of your user profile information on the Sauce Labs dashboard.  

Most Java users use one of two popular third party testing frameworks: TestNG or Junit. These links are for two example projects written in each. They are designed to run in parallel. You can clone them and add your own test cases if you want:

Running Tests in Parallel and Across Multiple Browsers

Tests can be run in parallel at two levels: you can run your tests in parallel,and you can run your tests in parallel across multiple browsers. For example, if you have 10 tests and run them serially on five browsers, this would be parallelism of five. You can also run tests across browsers and each test in parallel. Using our previous example, this would be 50 parallel tests (10 tests, five browsers). This requires that your tests are written in a way that they do not collide with one another. For more on this see Selenium WebDriver - Running Your Tests in Parallel blog.

For more information, check out the example scripts in our GitHub repo

Reporting on Test Results

The Java Helper Library will automatically send test names and pass/fail results to your Sauce Labs dashboard if you are using TestNG or JUnit as your framework.

If using other frameworks, then use the SauceRest Java Library to update the pass or fail status of the test.

You should also check out the topic Best Practice: Use Build IDs, Tags, and Names to Identify Your Tests for more suggestions on how to improve test reporting and using build numbers for your continuous integration platform.