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

When testing with Sauce Labs, there are ultimately three different types of tunnel scenarios: 

  • Ephemeral (short-lived): Start a tunnel when you start a build (specify a length for short-lived tunnel?)
  • Long-Running: Start one or more tunnels that remain active indefinitely, however, we recommend restarting them every 24 hours
  • Combination: Start a combination of Ephemeral and Long-Running tunnels

Which one is right for you? That depends on your testing goals, number of parallel tests, duration of testing, number of Sauce Connect Proxy users in your team.

Regarding of the type of tunnel you launch, it is important to be diligent about assigning names (tunnel identifiers) to each tunnel to distinguish them and ensure smooth testing.

We also recommend verifying if your team has a tunnels setup that you can share. Please note that tunnel sharing should only be undertaken by well-coordinated users. For more information on sharing Sauce Connect Proxy tunnels within your organization, see Sharing Sauce Connect Proxy Tunnels - Extended Team Management.

See the following sections for more information:

What You'll Need

  • If you haven't already, make sure you can cURL or ping the website or mobile app that you'll be testing from your computer. If you can't reach it, neither can Sauce Connect Proxy!

  • Check to see if you have any proxies that are required to access the public Internet

  • Review Basic Sauce Connect Proxy Setup for instructions on how to set your Sauce Labs username and access key and launch a tunnel
  • If you're using Jenkins, be sure to review Sauce Connect Proxy Jenkins Configuration
  • If you're using Bamboo, be sure to review Sauce Connect Proxy Bamboo Configuration

Ephemeral (Short-Lived) Tunnels

Sauce Connect Ephemeral tunnels – short-lived tunnels – are ideal for the following test situations: 

  • If you're testing from your laptop and start your tests from an Integrated Development Environment (IDE) or terminal

  • If you’re starting your builds/suites from a Jenkins or Bamboo server

  • If you plan to start and stop your tests quickly and need to be more hands-on
  • If you need to test potentially build-breaking changes like modifying the tunnel to fast-fail scripts/trackers, change the geolocation, or change how SSL/TLS encryption happens

How to Start an Ephemeral Tunnel From Your Local Workstation

One option to start Ephemeral tunnels is to do so from your local workstation.

  1. First, you'll want to set your Sauce Labs username and access key as environmental variables. For more information, see Best Practice: Use Environment Variables for Authentication Credentials.

  2. Run the simplest of startup commands to ensure that the tunnel starts:

    MacOS/Linux Example
    Windows Example
    > bin\sc -u %SAUCE_USERNAME% -k %SAUCE_ACCESS_KEY%

    Once you see a tunnel in Sauce Labs, you can start testing against a site that is hosted on your network. You can leave it up for as long as you'd like and test at a fairly reasonable volume. Start it and stop it as needed!

How to Start an Ephemeral Tunnel From a Continuous Integration (CI) Build Server

You can also launch Ephemeral tunnels from a continuous integration (CI) build server, where the code is being pulled from a repository. 

  1. When putting together test suites or builds from a CI build server, we recommend first creating an automated loop that contains the following steps:

    1. Build starts (scheduled or user-initiated).
    2. (Optional) Start an instance of the website or mobile app being tested.
    3. Script starts your tunnel on the server.
    4. Your tests start on Sauce Labs.

  2. Determine the number of tunnels you'll need for your tests. For this example, we'll use one tunnel. As a rule of thumb, if you're running less than 200 parallel tests, one tunnel is fine; for 200 or more parallel tests, you'll need two tunnels. For more information, please see System and Network Requirements for Sauce Connect Proxy

  3. How you start your tunnel is up to you. You can run a simple Bash shell script (or PowerShell script, if you're in Windows) that simply executes the start commands as if you were starting it locally:  


    NOTE: If you don't specify a Data Center Sauce Connect Proxy uses the US Data Center for SAUCE_DC by default. So for example if you need to run tests on the Sauce Labs EU Data Center, you need to modify the -x flag like so:

    $ /bin/sc -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY -i singleton-eu-tunnel -x 

Once you've established your automated loop, you should be able to kick off builds as needed, automatically. You won't need to worry about where a tunnel lives or how it starts!

Long-Running Tunnels

Long-Running tunnels are especially useful for large enterprise customers, who often set their tunnels to run automatically for 12-48 hours over the course of their testing. They are ideal for situations like the following:

  • If you're running a high number of parallel tests (50 or more)
  • If you have a test automation infrastructure that can utilize the Sauce Connect Proxy service and wish to have your Sauce Connect client component up and running for a long time (i.e., 12-48 hours) 
  • If you plan to share tunnels across teams. 

Long-Running tunnels go hand-in-hand with our High Availability Sauce Connect Proxy Setup, which allows you to run multiple tunnels to support a very high number of parallel tests. If you're part of a team of multiple people and/or departments running tests simultaneously on Sauce Labs, we strongly recommend utilizing Long-Running tunnels in High Availability Mode. Once you (or your systems administrator) set your Long-Running tunnel configuration for your account in Sauce Labs, the settings will be remembered in your account and you won't have to set them again. Here are some benefits to this:

  • When provisioning new user accounts, these tunnel settings will be ready and waiting for them when they log in
  • All Sauce Labs users in your organization will have immediate access to existing, launched tunnels
  • Redundancy; if a tunnel fails, tests will flow to the other tunnel(s)
  • Tunnel logs can be rotated automatically and used to troubleshoot as needed
  • If the infrastructure for your site under test changes, you will have a known configuration that works. Keeping a group of tunnels alive 24/7 is generally easier than setting up new tunnels for every change that happens.

How to Launch High Availability, Long-Running Tunnels via Command-Lines

Single Tunnel

A single tunnel that you'd start from your laptop or CICD system would look like this on the command line:

/Users/you/sc-<VERSION>-<PLATFORM>/bin/sc -u $SAUCE_USERNAME -k $SAUCE_ACESS_KEY -i my-single-tunnel-- --pidfile /tmp/

Multiple Tunnels

High Availability tunnels would look like this if they were run as part of a script or from the command line:

$ /Users/you/sc-<VERSION>-<PLATFORM>/bin/sc -u $SAUCE_USERNAME -k $SAUCE_ACESS_KEY --no-remove-colliding-tunnels -i main-tunnel-pool --se-port 0 --pidfile /tmp/ 

$ /Users/you/sc-<VERSION>-<PLATFORM>/bin/sc -u $SAUCE_USERNAME -k $SAUCE_ACESS_KEY --no-remove-colliding-tunnels -i main-tunnel-pool --se-port 0 --pidfile /tmp/ 

$/ Users/you/sc-<VERSION>-<PLATFORM>/bin/sc -u $SAUCE_USERNAME -k $SAUCE_ACESS_KEY --no-remove-colliding-tunnels -i main-tunnel-pool --se-port 0 --pidfile /tmp/ 

$ /Users/you/sc-<VERSION>-<PLATFORM>/bin/sc -u $SAUCE_USERNAME -k $SAUCE_ACESS_KEY --no-remove-colliding-tunnels -i main-tunnel-pool --se-port 0 --pidfile /tmp/
Code Block Legend

This command-line prevents the removal of identified tunnels with the same name and any default tunnels, if you're using them. Jobs will be distributed across these tunnels, enabling load balancing and High Availability. It is required when running High Availability tunnels to allow multiple tunnels with the same name. What happens if you don't use this command? By default, colliding tunnels (i.e., tunnels with the same identifier) would be removed when Sauce Connect is starting up. If you start another tunnel with the same identifier as an existing pool without adding --no-remove-colliding-tunnels, the new tunnel would be established, but all tunnels in the pre-existing pool would be closed.

-i main-tunnel-pool:
"-i" is shorthand for the --tunnel-identifier command. And "main-tunnel-pool" is the tunnel name; defining a name is required so that your tests can find your tunnels. This is required to start Long-Running tunnels.

--se-port 0:
Enables Sauce Connect to find the first available port for the Selenium Relay

--pidfile /some/dir/
File that auto-generates whenever a process for Sauce Connect starts. Must be unique per tunnel. To see where the file is saved, you can check the Sauce Connect Log.

For more information, Sauce Connect Proxy Command-Line Quick Reference Guide.

How to Keep Your Long-Running Tunnels Fresh

Tunnels running for an extended period of time (i.e., up to 48 hours), do not grow "stale"; they are actively and continuously used for running Sauce Labs website and mobile app tests throughout their duration. That said, keeping your Sauce Connect Proxy instances up and running for weeks or longer may result in maintenance difficulties, instability or performance degradation. To keep tunnels working their best, we recommend not letting your tunnels run for more than 24 hours, and you can utilize using rolling restarts to refresh them. This is a functionality that you or your systems administrator would need to build on your end. You can also write a script to recycle Sauce Connect clients daily or at the time of your choosing. 

Please note that if a tunnel fails or is absent, your tests will fail, which you'll be able to see from Sauce Labs. For a quick reference guide on how to start and stop tunnels, see How to Start and Stop Sauce Connect Tunnels (Startup and Teardown).

Combination Tunnels

With Sauce Labs testing, you may also choose to run a combination of Ephemeral and Long-Running tunnels. These are useful for large enterprise users.

For example, your team might have several Long-Running tunnels that are running, with testing in progress, but your developer colleague is working on a feature that needs to route traffic to a different staging service. In this case, you could set up an individual tunnel that routes traffic in a way that would cause all the other builds to fail. They could start this tunnel on their laptop at work and continue testing on sauce like normal without disrupting their co-workers.

  • No labels