Skip to main content

Selenium Grid and Sauce Labs

Testing new features and bug fixes is vital to enable quick software development. Selenium Grid helps with this by allowing concurrent execution of WebDriver tests across different browsers, platforms, and devices on multiple remote machines.

However, building your own testing infrastructure with Selenium Grid becomes challenging over time due to the continued releases of new browser versions, browser drivers, operating systems, and mobile devices. You'll need to invest a large amount of time to set up a fine tuned Selenium Grid that supports cross browser, cross platform, and cross device testing.

By executing your tests on Sauce Labs, in addition to having a solid testing infrastructure, you can also benefit from the following features:

  • Live debugging, video recording, command tracing, screenshots, and exception highlighting to enable easy debugging on the Sauce Labs tests results dashboard.
  • Sharing test results securely between team members by configuring users and teams.
  • Understanding how your application renders on every device and operating system by analyzing results from Front-End Performance Testing.
  • Interpreting test results over time and identifying failure patterns across different platforms with Insights.
  • Integrating your Sauce Labs test suite with CI/CD platforms.

What You'll Learn

  • How to extend Selenium Grid with Sauce Labs.
  • How to move from Selenium Grid to Sauce Labs.

What You'll Need

  • A Sauce Labs account (Log in or sign up for a free trial license).
  • Java 11 or higher installed on every machine part of Selenium Grid.
  • Browsers and browser drivers you want to support installed on each node.
  • Selenium Server JAR file from the latest release.

How Selenium Grid Works

Selenium is built on a client-server architecture, where Selenium Grid is the server. For details on how Selenium Grid works, its components, and how to set it up, see the Selenium Grid Documentation.

Running Tests on Selenium Grid

After following the steps to get Selenium Grid up and running, tests that run locally need to be modified to run remotely on Selenium Grid.

Below is a Java example where code is modified from using a local driver to use a remote driver. For extended examples on remote drivers, see Step 1: Create a Remote Session.

Check your Grid URL

The example assumes that your Grid is running on http://localhost:4444. Replace the URL with the one where your Grid is actually running.

Local execution
WebDriver driver = new ChromeDriver();

Extending Selenium Grid with Sauce

Setting up your own Grid can be simple at the beginning but as usage grows, and more platforms and browsers are needed, you will find yourself in the situation where a bigger infrastructure needs to be supported. Adding macOS and Safari or mobile devices and emulators can be challenging due to the hardware costs and very diverse requirements. Extending Selenium Grid with Sauce Labs is an excellent solution to add capacity and support more use cases.

Selenium Grid has a Relay feature that enables a local Grid to add Sauce Labs as an extra Node. In this way, Grid can enable more coverage to platforms and versions not present locally.

1. Create a toml Configuration File

A configuration file in toml format is needed to setup a Node and relay WebDriver sessions to Sauce Labs. For example, if your local Selenium Grid supports Chrome and Firefox on Linux, and you want to add support for Windows 11 and macOS, and also iOS and Android devices, you can configure those extra capabilities in the toml configuration file.

Click here to see an example toml configuration file.

For example, to support the following configuration settings:

OSBrowser/DeviceVersionConcurrent sessions
Windows 11Chrome1045
Windows 10Firefox10310
macOS Monterey (12)Safari155
iOS 15.4Safari on SimulatoriPhone 132
Android 12Chrome on EmulatorPixel 6 Pro2

Here is how the config.toml would look like:

detect-drivers = false

url = ""
configs = [
"5", '{"browserName": "chrome", "platformName": "Windows 11", "browserVersion": "104"}',
"10", '{"browserName": "firefox", "platformName": "Windows 10", "browserVersion": "103"}',
"5", '{"browserName": "safari", "platformName": "macOS 12", "browserVersion": "15"}',
"2", '{"browserName": "safari", "platformName": "iOS", "appium:platformVersion": "15.4", "appium:deviceName": "iPhone 13 Simulator"}',
"2", '{"browserName": "chrome", "platformName": "android", "appium:platformVersion": "12.0", "appium:deviceName": "Google Pixel 6 Pro GoogleAPI Emulator"}'
Sauce Labs endpoint URL

The example file shows the US West data center. See the different endpoints if you want to use another region.

2. Add a Node to your Local Grid

Finally, adding a new Node to your local Selenium Grid is possible through the following command:

java -jar selenium-server-<version>.jar node --config config.toml

With that, you will be able to send test requests to your local Grid and when the capabilities match, they will be redirected to Sauce Labs. Extra capabilities in sauce:options are also supported to have better readability on the test reports page at Sauce Labs.

3. Create a Remote Session Request

The following Java example shows how to create and send a session request to a local Grid with capabilities to match with Safari 15 on macOS Monterey served on Sauce Labs.

Use Credential Environment Variables

Set your Sauce Labs account credentials as environment variables rather than hard-coding them into all your scripts for efficiency and to protect them from unintended exposure.

Remote execution using an extended Grid with Sauce Labs
SafariOptions browserOptions = new SafariOptions();
browserOptions.setPlatformName("macOS 12");
Map<String, Object> sauceOptions = new HashMap<>();
sauceOptions.put("build", "<your build id>");
sauceOptions.put("name", "<your test name>");
sauceOptions.put("username", System.getenv("SAUCE_USERNAME"));
sauceOptions.put("accessKey", System.getenv("SAUCE_ACCESS_KEY"));
browserOptions.setCapability("sauce:options", sauceOptions);
RemoteWebDriver driver = new RemoteWebDriver(new URL("http://localhost:4444"), browserOptions);

Moving from Selenium Grid to Sauce

Supporting a new browser version in a local Selenium Grid requires a complete verification of its functionality before running your actual tests with it. In addition, providing features like video recording, logs, and screenshots, comes with the burden of building a custom test results dashboard, which needs provisioning storage for those files plus an automated archiving strategy.

With Sauce Labs, using new browser versions, platforms, or mobile devices, is as easy as setting the desired configuration options in your test.

A single line of code needs to be changed to execute the same test code directly on Sauce Labs. Instead of using http://localhost:4444 as a URL, a Sauce Labs endpoint URL should be used in the RemoteWebDriver. See the code sample below.

Local Grid
RemoteWebDriver driver = new RemoteWebDriver(new URL("http://localhost:4444"), browserOptions);

Use our Platform Configurator to auto-generate test configuration options in the language of your choice to copy and paste into your source code.

More Information