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

Table of Contents

The Basics of Using Tunnel Identifiers

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 test runs.

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.

Using Tunnel Identifiers for a High Availability Configuration

The number of recommended Sauce Connect tunnels to use in your Sauce Labs tests is dependent on two factors: your system and the number of parallel tests you plan to run. For these guidelines, see System and Network Requirements for Sauce Connect Proxy

With the High Availability Sauce Connect Proxy Setup, you can run tests using multiple Sauce Connect tunnels, for which you will need to create tunnel identifiers to manage them. You can also run multiple Sauce Connect tunnels as a pool that is treated as single tunnel. By default – when you don't use tunnel identifiers – traffic from jobs that are initiated using your account will use that unnamed tunnel automatically.

Tunnel identifiers are useful in situation where you'd want to run multiple Sauce Connect tunnels simultaneously; for example, when using one tunnel on your local machine and another tunnel on your continuous integration (CI) server.

NOTE: In a scenario where you're using tunnels with some tests, but not others, we recommend using identifiers for all of your tunnels. 

Using Tunnel Identifiers with Multiple Tunnels on Different Machines

This table shows how tunnels running on different machines with different tunnel identifiers will interact with each other when they start up. 

An Already RunningUnidentified TunnelTunnel AlphaTunnel Beta
When you start a new

Unidentified Tunnel
Will shut downWill remain upWill remain up
Tunnel Alpha
Will remain upWill shut downWill remain up
Tunnel Beta
Will remain upWill remain upWill shut down

To create a tunnel identifier, start Sauce Connect using the --tunnel-identifier flag (or -i) and provide your own unique identifier string.

Once the tunnel is up and running: to ensure that a job uses the correct tunnel, any tests that you want going through this tunnel will need to provide the correct identifier using the tunnelIdentifier desired capability. This step is important, as jobs will also automatically make use of unidentified tunnels.

This table shows what to expect when you are running jobs with both identified and unidentified tunnels. 

When you have No tunnels runningAn unidentified tunnel runningTunnel Alpha runningAn unidentified tunnel AND tunnel Alpha running
When tunnel-identifier is

Not provided
No tunnel is usedThe unidentified tunnel is usedNo tunnel is usedThe unidentified tunnel is used
Your tests don't workYour tests don't workTunnel Alpha is usedTunnel Alpha is used
Your tests don't workYour tests don't workYour tests don't workYour tests don't work

Additional Flags for Multiple Tunnels on the Same Machine

If you wish to run different tunnels on the same machine, you'll need to use additional flags to start them. Multiple tunnels on the same machine require different ports, logfiles and pidfiles. In the table below are the required flags:

A file used to record the process identifier. It can be erased or reused once the tunnel is shut down.
The location where Sauce Connect writes its logs. This can be reused or erased once the tunnel is shut down, but since Sauce Labs Support will sometimes request this file if you're having test issues, deleting it automatically isn't a great idea.
An internal Sauce Connect port. This simply needs to be a free port.
The tunnel identifier.

Here is an example of the flags being used:

sc --pidfile /tmp/ --logfile /tmp/sc2.log --scproxy-port 29999 -i my-tun2

Tunnel Identifier Examples

Visit the Sauce Labs Demonstration Scripts and setup a test example in your language of choice. Next, open to the desired test script and add the following Test Configuration Option in the sauce:options capability.

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

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.  If your testing needs permits, and should you decide to go with the High Availability Sauce Connect Proxy Setup, using Tunnel Identifiers gives you the ability to start multiple tunnels.

  • No labels