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
- A Sauce Labs account (Log in or sign up for a free trial license).
- Your Sauce Labs Username and Access Key.
- Have Sauce Connect Proxy installed on your local machine. Make sure it's the latest version - otherwise, you may run into technical issues.
- Review Sauce Connect Proxy System and Network Requirements to confirm that your system and network architecture will be compatible with Sauce Connect Proxy.
- Know your regional Sauce Labs Data Center.
- Understand what kinds of tests you're running:
- If you're using virtual machines or devices, see the instructions below.
- If you're testing real devices, see Setting Up for Real Device Cloud.
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
- Open your terminal and navigate to the Sauce Connect Proxy client bin folder on your local machine.
- 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
.\sc.exe -u %SAUCE_USERNAME% -k %SAUCE_ACCESS_KEY% --region %SAUCE_DC% --tunnel-name $TUNNEL_NAME
- 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.
- If you are using a name for your tunnel, add the
TUNNEL_NAMEto the capabilities section of your test script. Use the same name you used in Step 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.
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:
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
./sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -r $SAUCE_DC --tunnel-name sc-proxy-tunnel
.\sc.exe -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
tunnelNamecapability to your
Sauce Connect Proxy Basic Network Configuration
|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.|
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.
- Sauce Connect Proxy client calls REST API to start a tunnel.
- REST API initiates a request to system to create a new Tunnel VM.
- REST API tells the Sauce Connect Proxy client DNS name of the Tunnel VM.
- 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
- Selenium/Appium test code sends an HTTPS request to the VM or Real Device that was created for this test (e.g.,
- 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.
- Tunnel VM forwards this request to Sauce Connect Proxy client via the secure tunnel.
- Sauce Connect Proxy client forwards the request to Site Under Test (SUT).
- Site Under Test returns response to Sauce Connect Proxy client.
- Sauce Connect Proxy client sends response to Tunnel VM via secure tunnel.
- Tunnel VM sends response to Test VM.
- 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.