Skip to main content

Sauce Connect Proxy Basic Setup

The basic Sauce Connect Proxy setup is ideal for non-enterprise users with network configurations that require a proxy to open communication between Sauce Labs and their website or mobile app hosted locally or behind a firewall.

It is also a key step for any Sauce Connect Proxy 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.

What You'll Need​

Security Recommendation

We recommend setting your username and api key values as environment variables to protect them from exposure. They'll be reusable (you won't need to type them in every time).

Basic Setup without a Test Script​

See Sauce Connect Proxy Quickstart for instructions on how to run a Live (Manual) test on a locally hosted app.

Basic Setup with a Test Script​

  1. Open your terminal and navigate to the Sauce Connect Proxy client bin folder on your local machine.
cd sc-4.9.2-linux/bin
  1. From your command line terminal, launch a tunnel with the below commands.

You can also find the code snippet with your credentials populated from the Tunnel Proxies page, under 2: Authenticate & connect.

./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY --region $SAUCE_DC --tunnel-name $TUNNEL_NAME

-u (--user) and -k (--api-key) are required. While the -r (--region) and --tunnel-name flags are technically not required, we strongly recommend them for best performance.

  1. Select an appropriate test script. Options might include:
  • An existing test, if available.
  • Create a new test using an example from Sauce Labs Demonstration Scripts. Follow those instructions to configure the test before proceeding to the next step.
  1. If you are using a name for your tunnel, add the TUNNEL_NAME to the capabilities section of your test script. Use the same name you used in Step 1.
caps.SetCapability("tunnelName", "TUNNEL_NAME");
  1. When you see connected, verify that your tunnel is active.

Once you've confirmed that your network is configured for Sauce Connect Proxy, you can start new tunnels as needed. As a best practice, we recommend creating a new tunnel for each test suite or build and tearing it down at the end of your test.

You can continue using this basic setup or try a more advanced configuration, which is ideal for large scale, enterprise-level testing:

Test Not Working?​

If you're unable to connect, check with your network administrator about examining firewall settings for roadblocks. For more information, see Allowlisting for Restricted Networks.

Another possible issue is certificate authentication. The server hosting Sauce Connect Proxy may need to connect to Online Certificate Status Protocol (OCSP). See Certificate Handling for more information.

For troubleshooting specific errors or common issues, see Troubleshooting and Frequently Asked Questions.

Using Tunnel Names​

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

  • Launch a Sauce Connect tunnel as-is, without naming it. That default, unnamed tunnel will automatically be used for all automated tests. This can be useful for small organizations with a limited number of tests.
  • Recommended: Assign a name to help distinguish tunnels in a way that is meaningful to your organization. To accomplish this:

Example Configurations​

The following code samples demonstrate specifying a tunnel name when launching a tunnel and then referencing that tunnel in your automated test.

Launch a new tunnel on the SC_HOST using the Sauce Connect Proxy CLI and the --tunnel-name flag:

./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -r $SAUCE_DC --tunnel-name sc-proxy-tunnel
  • Ensure that your network configuration allows for communication between the SC Host, the Tunnel VM, and the SUT (site under test). See the basic network configuration diagram for further explanation.
  • Select an example from Sauce Labs Demonstration Scripts and follow the instructions to configure the test in your dev environment.
  • Navigate to the desired test script and add the tunnelName capability to your sauce:options.
caps.SetCapability("tunnelName", "sc-proxy-tunnel");

Architecture​

Sauce Connect Proxy Basic Network Configuration​

Basic network configuration diagram

Diagram Legend

TermDefinition
SC Host (Sauce Connect Host)The machine in your network on which the Sauce Connect Proxy app 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.
note

Sauce Connect Proxy must be on the same network as the website or mobile app being tested, but it is not required to set it up on the same machine.

Sauce Connect Proxy Tunnel Startup Process​

Every Sauce Connect Proxy tunnel spins up a fresh virtual machine (VM) that is used only for your tests. VMs are destroyed once the tunnel is closed.

Tunnel startup diagram
  1. Sauce Connect Proxy client calls REST API to start a tunnel.
  2. REST API initiates a request to system to create a new Tunnel VM.
  3. REST API tells the Sauce Connect Proxy client DNS name of the Tunnel VM.
  4. Sauce Connect Proxy client makes connection request to Tunnel VM using its DNS name.

The tunnel should now be established between the Sauce Connect Client and the Tunnel VM.

Sauce Connect Proxy Communication When Test is Running​

Network Traffic Flow through a Tunnel​

Network traffic flow diagram
  1. Selenium/Appium test code sends an HTTPS request to the VM or Real Device that was created for this test (e.g., GET www.saucedemo.com).
  2. Test VM or Device sends this request to Tunnel VM in order to access SUT.
    note

    The tunnel assignment depends on the tunnel-name that tells Sauce Labs what tunnel to use.

  3. Tunnel VM forwards this request to Sauce Connect Proxy client via the secure tunnel.
  4. Sauce Connect Proxy client forwards the request to Site Under Test (SUT).
  5. Site Under Test returns response to Sauce Connect Proxy client.
  6. Sauce Connect Proxy client sends response to Tunnel VM via secure tunnel.
  7. Tunnel VM sends response to Test VM.
  8. Test VM sends results back to Selenium/Appium test cloud.

Throughout the lifetime of a tunnel, Sauce Connect Proxy client will send status information to Sauce Labs REST API.

More Information​