The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing


External Resources

More Info

Page tree
Skip to end of metadata
Go to start of metadata


The contents of this page refer to the new RDC on Sauce platform. If you're looking for instructions on how to run Sauce Connect Proxy on our legacy RDC platform visit: Creating a Sauce Connect Tunnel for Legacy Real Device Cloud.

Real Device Cloud on Sauce Labs (RDC on Sauce) offers public and private mobile devices for users looking to expedite automated and live testing for their mobile apps. You can run a high volume of tests across a broad range of real devices without compromising performance, quality, or reliability.

With Sauce Connect Proxy, you’ll have a secure tunnel for testing applications and websites on your local machine (or behind a firewall) against devices and browsers in the Sauce Labs Real Device Cloud.  

See the following for more information:

What You'll Need


You must know your account details, including: 

NOTE: Sauce Labs recommends setting all of the values above as environment variables to protect your username and api key from exposure, and also for future convenience.

Security Considerations

Sharing Tunnel Access Across Your Organization

If you are currently using Extended Team Management, tunnel sharing will be enabled by default for your organization. For more information, see Sharing Sauce Connect Proxy Tunnels - Extended Team Management.

Restricting Tunnel Deployment to Organization Admins

If you'd like to restrict Sauce Connect Proxy tunnel deployment to Organization Admins only, follow the steps under Security Settings for Organizations > ALLOW ONLY ORGANIZATION ADMINS TO START SAUCE CONNECT PROXY TUNNELS.

Testing with Public Devices

In order to begin running tests on public devices using Sauce Connect Proxy or IPSec VPN, your Organization Admin must enable this option in their settings. Follow the steps under Security Settings for Organizations > ENABLE SAUCE CONNECT PROXY/VPN FOR PUBLIC CLOUD DEVICES.

Once the setting is enabled, all users across your organization can run live and automated tests on public devices over Sauce Connect Proxy or IPSec VPN. Each time you initiate a test, you'll see a temporary pop-up alert window with a reminder that the utilization of a trusted Sauce Connect Proxy or IPSec VPN connection combined with RDC public real device tests may not be compliant with your organization's network policy. 

Testing Against localhost (Android Device Testing Only) 

If you're running tests on Android devices, please be aware that testing with the address localhost (or the IP address is not supported with iOS devices or Android devices in Sauce Connect Proxy.

To work around this, add an entry in the hosts file on the machine on which you are running Sauce Connect Proxy with an entry for a dummy hostname (such as localtestsite) and the IP address Then, if you make requests for localtestsite in your tests, these will be sent through the Sauce Connect tunnel to localhost, which is the machine where Sauce Connect Proxy is running.

SSL Bumping

While rare, there are some test cases that will require you to disable SSL Bumping when using Sauce Connect Proxy in order to avoid certificate issues. For more information, see Sauce Connect Proxy and SSL Certificate Bumping.

Selecting the Tunnel to Use

To run a test on a real device using Sauce Connect Proxy, you will need to create a proxy tunnel specifically for the real device cloud, separate from the one used to connect to virtual devices.

Sauce Connect Proxy can have multiple tunnels running simultaneously, as described in High Availability Sauce Connect Proxy Setup. You can select which tunnel to use in a real device test in the same way as you would any other type of automated test.  

  1. Start Sauce Command Proxy from the command line, providing an -i (--tunnel-identifer) to start a new tunnel with that identifier. 


    SAUCE_RDC_USERNAME refers to your Sauce Labs Usernamewhere:

    1. SAUCE_RDC_ACCESS_KEY refers to your Sauce Labs Access Key.
    2. SAUCE_DC refers to the data center API endpoint. For more information, see Data Center Endpoints.
    3. TUNNEL_ID refers to the tunnel identifier.

    So an example would look like this:

    $ /bin/sc -u $SAUCE_RDC_USERNAME -k $SAUCE_RDC_ACCESS_KEY -x '' -i rdc-on-sauce-tunnel-us
  2. In your device testing script, specify the tunnel name with tunnelIdentifier in your desired capabilities, as shown in this Java example:

    Example `tunnelIdentifier` Java Snippet
    final DesiredCapabilities capabilities = new DesiredCapabilities();
    	capabilities.setCapability("username", System.getenv("SAUCE_RDC_USERNAME"));
    	capabilities.setCapability("accessKey", System.getenv("SAUCE_RDC_ACCESS_KEY"));
    	capabilities.setCapability("platformName", "Android");
    	capabilities.setCapability("platformVersion,"  "81.0");
    	capabilities.setCapability("deviceName", "Samsung_Galaxy_Note_5_real"); // Will only run on the specified device
    	capabilities.setCapability("tunnelIdentifier", "rdc-on-sauce-tunnel-us");
    final AndroidDriver driver = new AndroidDriver(new URL(""), capabilities);

Selecting a Real Device Data Center

Sauce Connect Proxy with Real device testing uses different endpoints from the Virtual Device Cloud, and because you're using a different endpoint, you will need to create a separate tunnel for your real device tests. Therefore you will need to adjust both the data center URL in which you deploy a tunnel (REST API endpoint), as well as the target URL in your automated tests (OnDemand Endpoint).

Data Center Endpoint Examples

When launching a Sauce Connect Proxy tunnel, you need to specify the targeted data center by placing an -x flag along with the desired endpoint. The -x flag defines the specific data centers other than the default (US West). For specific data center endpoint details, see: Data Center Endpoints.

Mac OSX / Linux Example
$ /bin/sc -u $SAUCE_RDC_USERNAME -k $SAUCE_RDC_ACCESS_KEY -x '' -i rdc-on-sauce-tunnel-us
Windows Example
> \bin\sc -u %SAUCE_RDC_USERNAME% -k %SAUCE_RDC_ACCESS_KEY% -x '' -i rdc-on-sauce-tunnel-us
Mac OSX / Linux Example
$ /bin/sc -u $SAUCE_RDC_USERNAME -k $SAUCE_RDC_ACCESS_KEY -x '' -i rdc-on-sauce-tunnel-eu
Windows Example
> \bin\sc -u %SAUCE_RDC_USERNAME% -k %SAUCE_RDC_ACCESS_KEY% -x '' -i rdc-on-sauce-tunnel-eu

OnDemand Endpoint Examples

In order to ensure you're testing against the correct data center, you'll need to add the correct OnDemand endpoint when you instantiate a MobileDriver in your automated test:


Java Snippet: Driver Setup for US Data Center
final AndroidDriver driver = new AndroidDriver(new URL(""), capabilities); 
Java Snippet: Driver Setup for EU Data Center
final AndroidDriver driver = new AndroidDriver(new URL(""), capabilities); 

Additional Support

If your tunnel launch fails with message "Failed to check for existing tunnels," contact our support team to verify that you have Sauce Connect Proxy access enabled on your account. 

More Information