The Basic Sauce Connect Proxy setup is ideal for non-enterprise users with network configurations that require a proxy to open up communication between Sauce Labs and their web or mobile app.

It is also a key step for any Sauce Connect deployment as a way to verify if you need help from network administrators to complete the configuration. For details, see Validating Your Basic Sauce Connect Proxy Setup.

See the following sections for more information:

What You'll Need

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.

Validating Your Basic Sauce Connect Proxy Setup

Once you've downloaded the Sauce Connect Proxy, you can validate that it works on your network by completing the following steps:

  1. Launch a tunnel with the following flags, per the Sauce Connect Proxy Command Line Reference:



  1. Select an appropriate test script. Options might include: 

  2. If you are using an tunnel identifier, add the following to the desired capabilities of  the test: 

    caps.SetCapability("tunnelIdentifier", "TUNNEL_ID");
    'tunnelIdentifier': 'TUNNEL_ID'
    caps.SetCapability("tunnelIdentifier", "TUNNEL_ID");
    'tunnelIdentifier': 'TUNNEL_ID'
    tunnelIdentifier: 'TUNNEL_ID',

Where TUNNEL_ID is the identifier or name of the tunnel from step 1. 

4. When you see connected, log in to Sauce Labs and go to Tunnels. Under Active Tunnels, you should see the tunnel you've just started. 

5. Your next step depends on the outcome of the test: 

Congratulations! You're ready to begin automated testing on your local network.

Test Not Working?

If you're unable to connect, there are a few possible explanations: 

Next Step: Starting Tunnels as Needed

Once you've confirmed that your network is configured appropriate for Sauce Connect Proxy, you can start new tunnels as needed.

It is important to be aware of the various options you have for configuring tunnels: 

As a best practice, Sauce Labs recommends creating a new tunnel for each test suite or build and tearing it down at the end of the test. 

Basic Network Configuration Diagram

Diagram Legend



SC Host (Sauce Connect Host)The machine in your network on which the Sauce Connect Proxy application is running. In this setup, it has a direct connection to the internet.
SUT (Site Under Test)The site that you're testing. It is on the same local network as the SC Host machine.
Tunnel VM (Tunnel Virtual Machine)

Virtual machine that hosts Sauce Connect on the Sauce Labs side.

REMINDER: Sauce Connect must be on the same network as the website or mobile app under test, but it is not required to set it up on the same machine.

Using Tunnel Identifiers with Sauce Connect Proxy

When launching a Sauce Connect tunnel for automated web and mobile app tests, you have two options:

Sauce Labs recommends using tunnel identifiers so you can have more control and monitoring capability over your tunnel.

EXAMPLE: Automated Test with Sauce Connect Proxy Tunnel Identifiers

Below is an example of how to designate tunnels based on the tunnelIdentifier option so that it works properly with an automated test.

Launch a new tunnel on the SC_HOST with the following flags, per the Sauce Connect Proxy Command Line Reference:

$ sc_download/bin/sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -x $SAUCE_DC -i sc-proxy-tunnel
> sc_download\bin\sc.exe -u %SAUCE_USERNAME% -k %SAUCE_ACCESS_KEY% -x %SAUCE_DC% -i sc-proxy-tunnel

caps.SetCapability("tunnelIdentifier", "sc-proxy-tunnel");
'tunnelIdentifier': 'sc-proxy-tunnel'
caps.SetCapability("tunnelIdentifier", "sc-proxy-tunnel");
'tunnelIdentifier': 'sc-proxy-tunnel'
tunnelIdentifier: 'sc-proxy-tunnel',

Sauce Connect Proxy Tunnel Startup Process

Every Sauce Connect tunnel spins up a fresh virtual machine (VM) that is used only for your tests; VMs are destroyed once the tunnel is closed. A recommended Sauce Connect best practice is to create a new tunnel for each test suite or build and tear it down at the end of your test. 

DIAGRAM: Sauce Connect Proxy Tunnel Startup

STEP 1: Sauce Connect Client calls REST API to start a tunnel.

STEP 2: REST API initiates a request to system to create a new Tunnel VM.

STEP 3: REST API tells the Sauce Connect Client DNS name of the Tunnel VM.

STEP 4: Sauce Connect Client makes connection request to Tunnel VM using its DNS name.

At this point, the tunnel is established between the Sauce Connect Client and the Tunnel VM.

Sauce Connect Communication When Test is Running

DIAGRAM: Network Traffic Flow When a Test is Run Through a Sauce Connect Tunnel

STEP 1: Selenium/Appium test code sends an HTTPS request to the VM or Real Device that was created for this test (for example, GET

STEP 2: Test VM or Device sends this request to Tunnel VM in order to access SUT.

STEP 3: Tunnel VM forwards this request to Sauce Connect client via the secure tunnel.

STEP 4: Sauce Connect Client forwards the request to Site Under Test (SUT).

STEP 5: Site Under Test returns response to Sauce Connect Client.

STEP 6: Sauce Connect client sends response to Tunnel VM via secure tunnel.

STEP 7: Tunnel VM sends response to Test VM.

STEP 8: Test VM sends results back to Selenium/Appium Test cloud.

Throughout the lifetime of a tunnel, Sauce Connect Client sends status information to Sauce Labs REST API.

More Information

Now that you're up and running with a Basic Sauce Connect Proxy Setup, we recommend reviewing the following topics: