This course covers the basic setup and use of the Sauce Connect Proxy Tunnel, which is a tool created by Sauce Labs that customers can use to establish a secure, private connection between your app and the Sauce Labs Cloud.

What You'll Need

In order to follow along with the course, you will need a few things set up ahead of time:

This tutorial gives examples written in Java, using the JUnit4 test runner, as well as the Maven build tool.

Skills and Knowledge

To find out more about Sauce Connect Proxy architecture, see our Sauce Connect Proxy whitepaper.

Sauce Connect Proxy is a secure tunneling application that allows you to connect the Sauce Labs cloud to applications you want to test that are hosted on your local machine or behind a firewall. In this lesson, you will learn to:

Video

Set Up Sauce Connect

In many cases, testers need to run their tests on internal sites. These can be dev/staging versions of their production site or actual internal sites only employees use. In either case, these sites are not available out in the open internet for sauce to access.

The option shown here is using Sauce Connect Proxy which uses a proprietary TLS protocol to encrypt traffic between Sauce Labs and your network and servers. Learn more about Sauce Connect in the whitepaper.

Download Sauce Connect Proxy

The first step is to download the Sauce Connect Proxy client — available in our Sauce Connect Proxy Installation documentation — and extract the contents of the .zip or .gz download package. You can also get the software on the Sauce Labs platform under Tunnels.

Tunnels Software

Once you've extracted the contents, take the Sauce Connect Proxy folder and move it into another directory. In this example, the Sauce Connect software has been moved into the Documents folder.

Tunnel Software Directory

Set Sauce Labs Environment Variables

You will need to have environment variables set for Sauce Labs on your local machine or CI tool in order to run your tests.

Watch this video to learn how to set up environment variables with your Sauce Labs credentials on a Mac, or view the instructions for Windows.

You also have the option to store all of the values for your Sauce Connect tunnel in a .yml file, and run the tunnel with the command:

sc -c config.yaml

Example YAML File

$ cat ~/sc-us-west.yml
---
region: us-west
user: <SAUCE_USERNAME>
api-key: <*******************>
direct-domains:
- domain1
- domain2
tunnel-name: <your-tunnel>

Start the Tunnel

Sauce Connect tunnels are initiated from the client side to allow applications behind a firewall to communicate and test on the Sauce Labs Cloud. Start by going to the Tunnels tab in Sauce Labs.

Tunnels Menu

You can copy the command that you will find at the bottom of the Tunnels page, and paste this into your terminal as well, instead of typing what is above. Once you paste, append the command line with -i . In this example, I've called mine linds-proxy-tunnel.

Command to run tunnel

Your command should look like this:

Terminal command to run tunnel

Navigate to the folder using the terminal where you saved the Sauce Connect download (this one is in Documents/sc-4.6.2-osx). Next, type and run the command below. Make sure to fill in your credentials (username after the -u command and access key after -k) and add your tunnel name (aka tunnel identifier) after the -i command. Hit enter and you should see your tunnel up and running.

bin/ sc -u <SAUCE_USERNAME> -k <SAUCE_ACCESS_KEY> -i <SAUCE_TUNNEL_NAME>

You should see the output in the terminal letting you know Sauce Connect Proxy is up and running:

Sauce Connect is up and running

Stop the Tunnel

You can stop any tunnel that you have running by hitting cntrl + c

Learn more about the other commands you can use to configure your tunnel at Sauce Connect Proxy CLI Reference.

Terminal running tunnelTunnel running on Sauce Labs

Note

Live (Manual) Tests with Sauce Connect

You can easily run any manual tests that you do with Sauce Connect proxy. Simply go to the Live, Cross Browser testing dashboard, and choose to use any proxy tunnel that is available to you for your manual tests.

Tunnel running on Sauce Labs

This video is intended to show an example for how to update your test capabilities, using this example test written in Java, JUnit4, with Maven and InteliiJ. Iin this lesson you will:

Video

Run a Test with Sauce Connect Proxy

Start Your Tunnel

Navigate in terminal to the location where you saved the sc-x.x.x-osx file, then run the command that you copied from the Tunnels tab in the saucelabs dashboards

bin/sc -u your-username -k ******************** -i your_tunnel_name

Note

Set Sauce Connect Tunnel Capabilities

This example shows how to set the capabilities in an example Java Test Suite, written with the JUnit4 test runner, and run and managed using Maven. See the example suite this is created from.

Update Test Code

This test is importing environment variables in the tests/Config.java file, using the SAUCE_USERNAME and SAUCE_ACCESS_KEY you have set up on your machine or CI tool. You will set up an environment variable for your SAUCE_TUNNEL environment variable as well. This variable will store the tunnel identifier, so after you start up a Sauce Connect tunnel, you can run your tests using it.

Add the variable sauceTunnel in your Config.java file, at the bottom of the list of variables:

// filename: tests/Config.java
//...
    public static final String sauceTunnel = System.getenv("SAUCE_TUNNEL");
}

Next, in BaseTest.Java, you are going to add in a third, else if statement that accounts for when you are running a test with Sauce Connect. It's almost exactly the same as the case when the host is "saucelabs" except you will be adding in the Sauce Option for the tunnel

// filename: tests/BaseTest.java
// ...
else if (host.equals("saucelabs-tunnel")) {
    MutableCapabilities sauceOptions = new MutableCapabilities();
    sauceOptions.setCapability("username", sauceUser);
    sauceOptions.setCapability("accessKey", sauceKey);
    sauceOptions.setCapability("name", testName);
    sauceOptions.setCapability("tunnelName", sauceTunnel);
    MutableCapabilities capabilities = new MutableCapabilities();
    capabilities.setCapability("browserName", browserName);
    capabilities.setCapability("browserVersion", browserVersion);
    capabilities.setCapability("platformName", platformName);
    capabilities.setCapability("sauce:options", sauceOptions);
    String sauceUrl = String.format("https://ondemand.saucelabs.com/wd/hub");
    driver = new RemoteWebDriver(new URL(sauceUrl), capabilities);
    sessionId = ((RemoteWebDriver) driver).getSessionId().toString();
    sauceClient = new SauceREST(sauceUser, sauceKey, DataCenter.US);
}

// ...

In this case, which you have named saucelabs-tunnel, when you run your test, you will set all the capabilities you did before, but notice how the sauceTunnel variable is being used by setCapabilities, right under where you set the testName capability. The reason that we need to create a whole new case is that the tests will error if they are given a tunnel identifier, and it is not used.

Run Your Tests

You will want to restart your terminal and run source ~/.bash_profile so your machine looks for the new SAUCE_TUNNEL variable.

Now try running the command in terminal:

mvn clean test -Dhost=saucelabs-tunnel

Tunnels and Tests

Note

You will run your test through the tunnel, and when you log into the SauceLabs UI, you should see the tests being run, and that there is an active tunnel:

Active Tunnel

You can see example code for this lesson here.

Sauce Connect Architecture

To learn more about what is happening when you use Sauce Connect tunnel, see the documentation about how network traffic flows through a Sauce Connect Tunnel

Shared Tunnels

Many companies may also choose to have their organization set up Shared Tunnels on Sauce Labs, which anyone in their organization can use without having to worry about configuring their own tunnel.

To use a shared tunnel, simply check the Tunnels tab to see your shared tunnels you have access to. You should be able to see the shared tunnel name, the name of the owner of the tunnel as well, as an indication that it is a shared tunnel, then use the tunnelIdenifier and the tunnelOwner in your test suites' capabilities:

Shared Runnel Shared Runnel

Final Code

See the example test suite with capabilities set for Sauce Connect. Final Java Base Test Code

Final Java Config Code

This lesson will walk you through the basic things you will need to do if you are having issues connecting and running a Sauce Connect Proxy Tunnel. These steps include:

Video

Troubleshooting with Sauce Connect

Find Out About Your Network

The first thing you may need to do is check that the machine where you installed the Sauce Connect proxy will allow you to access Sauce Labs and your app. For example, if you installed Sauce Connect on a virtual machine that has a firewall or is in a DMZ, you may have issues communicating.

If you are unable to start a tunnel, try checking whether you can communicate with saucelabs.com and the app you are testing.

Check Communication With Sauce Connect

From the machine you wish to run the Sauce Connect proxy from, use ping to check that you machine can communicate with Sauce Labs Server:

ping saucelabs.com

Tunnels Menu

See other commands you can use

Check Communication With App Under Test

From the machine you wish to run the Sauce Connect proxy from, you also want to check and make sure you can communicate with the application you are testing against. Again, use ping to check that your machine can communicate with the example site (like saucedemo.com)

ping saucedemo.com

Tunnels Menu

Logically, if the environment your tests are on cannot communicate with both of these, then your tests will not work. If the testing connection fails, your terminal should return a message such as:

cannot resolve thisshouldntwork.saucelabs.com: Unknown host

Some other options for troubleshooting include:

Other Common Tunnel Issues

When you have issues with starting a tunnel, and you have verified a firewall isn't an issue, there are several reasons that you might see an error like this:

Error message

Wrong Username or Access Key

If you are using the wrong SAUCE_USERNAME or SAUCE_ACCESS_KEY. Check that your environment variables are named correctly, and that you haven't regenerated your access key.

Regenerate access key

Tunnel Collision

Sometimes more than one tunnel is created with the same name, which is known as a ‘collision'. What will likely happen is that the first tunnel will stop running, and the new one will start up with the same name. You will get an error like this:

To prevent this from occurring, while starting more than one tunnel with the same name, use the --tunnel-pool flag.

File Upload Limit

If you are sending a large amount of test or application files to Sauce Labs with Sauce Connect, the file limit set on your machine for upload may affect Sauce Connect. If you are having issues or get a warning like:

[30070] PROXY error 24 (Too many open files) on listener

See the knowledge base article on increasing your open file limit.

Generate Logs

If you are having issues with your Sauce Connect Tunnel, you know your network connection is not the issue, and you have tried all of the above, generating logs as described in the next lesson.

There are a many options you can use to change the settings and options for your Sauce Connect Tunnel. This lesson will cover the most commonly needed options for a typical user. In this lesson, you will learn to:

You can find all the flags that you can use when running Sauce Connect in the Sauce Connect Proxy CLI Reference.

Video

Sauce Connect Options for Users

Check Your Sauce Connect Version

Sometimes it's important to see if you have the most up to date version of Sauce Connect so you can use the latest features and functionality using the sauce connect --version flag:

bin/ sc -u your-username -k your-accesskey -i your-tunnelname --version

Note

Generate Verbose Logs

If you are having trouble running your tests, and were not able to get it working with troubleshooting in the previous lessons, verbose logs will provide mode information that can help give you hints as to what is going wrong.

To generate a verbose log, try to start your tunnel adding in the -v flag for verbose logging:

bin/ sc -u your-username -k your-accesskey -i your-tunnelname -v

When the CLI outputs information about your sauce tunnel, you will see a file location for your logs:

Log File location

This log will generate a temporary file, which you can open with your terminal (cut and paste the log file location):

Log File open

Most often this file will be used to sent to Sauce Labs Support (or email help@saucelabs.com) so they can help you troubleshoot your issues.

Output Your Log Files to a Certain Location

If you want to dictate where log files will be stored, you can add the flag --logfile /filepath/to/logs to the command when you run Sauce Connect.

For example, if you created a directory called logfiles in your Documents folder to store your files, start Sauce Connect and create a new log called log1 in that directory.

bin/ sc -u your-username -k your-accesskey -i your-tunnelname -v --logfile ../logfiles/logfile-name

and if you check you should see Documents/logfiles/log1.

Save a log file

Specify the Sauce Data Center

Depending which data center (us-west-1, eu-central-1, etc.) you are running your tests in, you may want to change which data center your tunnel is running through (default us-west-1). See the list of Sauce Connect endpoints.

Simply add a flag for the data center endpoint like -x https://data-center-1.saucelabs.com/rest/v1 when you launch your tunnel:

bin/ sc -u your-username -k your-accesskey -i your-tunnelname -x https://eu-central-1.saucelabs.com/rest/v1

Use a different data center

Traffic Routing

When you are using Sauce Connect tunnel, there may be some situations where you want all your traffic to be sent through the Sauce Connect tunnel for security purposes.

Sometimes, however, sending everything to Sauce Labs through a tunnel may cause your tests to take a long time to execute, and you would want to send some requests directly to Sauce Labs, without using a tunnel.

Direct Domain Traffic

To specify certain domains whose traffic you don't want to go through the tunnel, simply add a -D flag with the argument: "*.domainName.com, *.otherDomainName.net", to the command when you run your tunnel.

As an example, if you are starting up a tunnel, and you want all traffic to and from https://www.saucedemo.com/ be sent directly to Sauce Labs (not through a tunnel) you would start your tunnel with the command:

bin/ sc -u your-username -k your-accesskey -i your-tunnelname -D "*.saucedemo.com/"

Tunnel Domain Traffic

If you would like to do the opposite and make sure that all traffic is not run through a tunnel, except for certain domains, you would use the -T flag with the name of the domain you do want run through the Sauce Connect tunnel.

bin/ sc -u your-username -k your-accesskey -i your-tunnelname -T "*.sensitiveDomain.com/"

SSL Bumping

When users communicate with applications over the internet, they use TLS (successor of SSL) protocol to make sure they are communicating securely. One part of this protocol requires that the app the user is communicating with provides a secure ‘certificate' to help verify the identity of server it is sending information to.

Video

SSL Bumping with Sauce Connect

When developers create and test an app, they typically use self-signed (considered invalid SSL certificates), which are not trusted by stock browsers, such as those installed on the Sauce Labs infrastructure. This means that when you are running Selenium tests, the communication with the browser may be interrupted with security warnings that can't be dismissed by Selenium.

Error- cannot access website

When developers test an internal app they are developing, or one used in a staging environment, often they won't have a publicly-signed network certificate for that app, which means that most likely security warning from the browser will cause your tests to fail.

To combat test failures caused by websites without valid SSL/ TSL certificates, Sauce Connect Proxy has a security feature called SSL Bumping that automatically re-signs certificates to allow network traffic, when they are run through a Sauce Connect Tunnel.

Disable SSL Bumping

If you have a valid certificate for your application, you don't need to use SSL bumping. There are also cases where SSL bumping doesn't help avoid security warnings that will cause tests to fail and you will want to disable it.

To disable SSL bumping, you would want to add the -B all, -B domain1.com, domain2.com or --no-ssl-bump-domain.com flag when you start your tunnel, like so:

bin/ sc -u your-username -k your-accesskey -i your-tunnelname -B all

Situations To Disable SSL Bumping

If you have a certificate that is recognized by Sauce Labs devices, and one of the following is true about your application, you would want to use the -B all flag to disable SSL bumping:

Resources

Support

Sauce Connect logs are hard, and we have experts to help you. Visit support.saucelabs.com to get help with your Sauce Connect issues. Having log files ready will help speed up the process.

Install Using cURL

To Install Sauce Connect on Linux, and add add sc to your system PATH, use the commands:

cd ~/
curl -LO https://saucelabs.com/downloads/sc-4.6.5-linux.tar.gz
tar xvf ./sc-4.6.5-linux.tar.gz
cp ./sc-4.6.5-linux/bin/sc ~/bin/sc

cp ./sc-4.6.5-linux/bin/sc ~/bin/sc