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

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 24 Next »

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 adminstrators 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

Validating Your Basic Sauce Connect Proxy Setup

Once you've established your Sauce Connect proxy connection(s), you can validate that it works properly by following the steps below.
  1. Launch a new tunnel with the following flags, per the Sauce Connect Proxy Command Line Reference:

    $ bin/sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -x $SAUCE_DC -i sc-proxy-tunnel

    For more information on the above variables, visit the section: Starting Sauce Connect Proxy for more information.

  2. Select an example from Sauce Labs Demonstration Scripts, and follow the instructions to configure the test.

  3. Navigate to the desired test script and add the following Test Configuration Option.

    caps.SetCapability("tunnelIdentifier", "sc-proxy-tunnel");
    'tunnelIdentifier': 'sc-proxy-tunnel'
    caps.SetCapability("tunnelIdentifier", "sc-proxy-tunnel");
    'tunnelIdentifier': 'sc-proxy-tunnel'
    tunnelIdentifier: 'sc-proxy-tunnel',
  4. If the test succeeds, you should see Sauce Connect Proxy icon appear next to your test in the SauceLabs Dashboard! 

Congratulations! You're ready to begin automated testing with our Sauce Labs Continuous Testing Cloud.

Test Not Working?

If you're unable to connect, your network administrator needs to examine the firewall setting(s) for any roadblocks. That person, or team, might need to adjust network rules for Sauce Labs domain names to allow Sauce Connect Proxy to make outbound connections to Sauce Labs. 

NOTE: While some IT teams might prefer to use whitelisting IP addresses as an alternative to using Sauce Connect Proxy altogether, we strongly discourage this as explained in Why Sauce Labs Recommends Sauce Connect Proxy Over Whitelisting IP Addresses.

There could also be an issue with Sauce Labs certificate authentication. The server hosting Sauce Connect may need to connect to Online Certificate Status Protocol (OCSP) and/or Certificate Revocation List (CRL) services. Please see Sauce Connect Proxy Certificate Handling for more information.

For troubleshooting specific errors or common issues, refer to the Sauce Connect Proxy Troubleshooting guide and Sauce Connect Proxy FAQs.

Basic Configuration Network Diagram

DIAGRAM: Basic Configuration for Sauce Connect Proxy

Diagram Legend



SC Host (Sauce Connect Host)The machine in your network on which the Sauce Connect 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 you're testing, but it is not required to set it up on the same machine.

Starting Sauce Connect Proxy

  1. After extracting the Sauce Connect download files onto your machine, go to the install directory and run sc with the -u and -k arguments to authenticate against your Sauce Labs account and establish the Sauce Connect tunnel.

    When running in Mac or Linux:
    sc_download/bin/sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY
    When running in Windows:
    sc_download\bin\sc.exe -u YOUR_USERNAME -k YOUR_ACCESS_KEY

    By default, running the sc.exe command as above will start a tunnel for Virtual Cloud tests in the US Data Center. There is a command-line option called -x (--rest-url) that you'll need to use if you are testing on the Real Device Cloud and/or testing in the EU data center. If you are starting a tunnel for Real Device tests, see Sauce Connect Proxy Setup for Real Device Cloud (RDC)

    The appropriate command-line to start a tunnel for Real Device tests and/or the EU Data Center can be found below: 

    When connecting to the EU Data Center for Virtual Cloud tests:
    sc_download/bin/sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY -x
  2. When you see connectedlog in to your Sauce Labs account and click the Tunnels dashboard link. Under Active Tunnels, you should see the tunnel you've just started.  

Using Sauce Connect Proxy Tunnels for Automated Tests

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

  • Launch a Sauce Connect tunnel as-is, without identifying it. That "default," unnamed tunnel will automatically be used for all automated tests run.
  • Assign a name to your tunnel – known as a Tunnel Identifier – which will give you control and monitoring capability over your tunnel. To accomplish this, you'll need to assign the Tunnel Identifier(s) when starting up Sauce Connect and launch a tunnel with the -i (--tunnel-identifier) command-line. Then, you'll need to use the tunnelIdentifier option in the desired capabilities of your automated tests. This will trigger your tests to request a specific Sauce Connect tunnel to run your tests through that tunnel. 

We recommend the latter option. Here's how it works: Let's say your tunnel is named myTunnel01. You would need to set this option as "tunnelIdentifier": "myTunnel01". If you are starting and stopping Sauce Connect Proxy programmatically, ensure your tunnel always launches with the same name by passing the identifier flag, -i, with your authentication credentials, for example: bin/sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY -i myTunnelO1.

Once you've completed the Basic Sauce Connect Proxy Setup, should you decide to go with the High Availability Sauce Connect Proxy Setup, using Tunnel Identifiers gives you the ability to start multiple tunnels.

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:

  • No labels