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 Running||Unidentified Tunnel||Tunnel ||Tunnel |
|When you start a new|
|Unidentified Tunnel||Will shut down||Will remain up||Will remain up|
|Tunnel ||Will remain up||Will shut down||Will remain up|
|Tunnel ||Will remain up||Will remain up||Will 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 running||An unidentified tunnel running||Tunnel ||An unidentified tunnel AND tunnel |
|When tunnel-identifier is|
|Not provided||No tunnel is used||The unidentified tunnel is used||No tunnel is used||The unidentified tunnel is used|
|Your tests don't work||Your tests don't work||Tunnel ||Tunnel |
|Your tests don't work||Your tests don't work||Your tests don't work||Your 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:
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
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.