Frequently Asked Questions

Can Sauce Connect create a tunnel from behind a corporate proxy?

No, your IT or ops team makes an exception only for the machine that Sauce Connect is on. The traffic being sent through Sauce Connect is not regular HTTP (Sauce Connect encrypts everything and uses a more robust protocol to make sure everything makes it to the other end), and it can't be sent through HTTP proxies.

If the current environment you're testing with requires you to proxy your outgoing traffic, you should discuss with your ops team or IT department about making an exception for outgoing traffic over port 443 to *.saucelabs.com. This doesn't need to be for the complete network, only for the machine you intend to run Sauce Connect on.

What is Sauce Connect's architecture?

Read our Sauce Connect System Security Diagram to understand how it works and what our recommendation is for setting it up.

Will I need to whitelist IPs or open any ports?

No, Sauce Connect doesn't require you do either of those things. This secure tunnel is used only by you and accessible over outgoing ports 80 and 443. (Please note that Sauce Manual Testing requires certain ports to be open. Details can be found here.)

Should I use Sauce Connect for my public test environment too?

We think so! Sauce Connect maintains a smart cache in our side of the tunnel, allowing us to pull static content such as images, css or js files only once for all your tests. This considerably reduces traffic through the tunnel and relieves your web server of excess load.

Can I reuse a tunnel between multiple accounts?

Tunnels started by an account can be reused by its sub-accounts. To reuse a tunnel, start Sauce Connect with the special --shared-tunnel parameter from the main account in your account tree. For example:

java -jar Sauce-Connect.jar --shared-tunnel parentAccount parentAccountsAccessKey

Once the tunnel is running, provide the special "parent-tunnel" desired capability on a per-job basis. The value of this capability should be the username of the parent account that owns the shared Connect tunnel as a string. Here's an example (this test should can run using Auth credentials for any sub-account of "parentAccount"):

capabilities['parent-tunnel'] = "parentAccount"

That's it! We'll take care of the rest by making the jobs that request this capability route all their traffic through the tunnel created using your parent account (parentAccount, following our example).

Can I run multiple tunnels for a single account?

In its default mode of execution, one Connect instance will suffice all your needs and will require no efforts to make cloud browsers driven by your tests navigate through the tunnel.
Just start Connect, all traffic from jobs under the same account will use it transparently. Stop that tunnel, all jobs will stop to do so and attempt to find your web servers through the open internet.

Using identified tunnels, you can start multiple instances of Connect that will not collide with each other and will not make your tests' traffic transparently tunnel through.
This allows you to test different localhost servers or access different networks from different tests (a common requirement when running tests on TravisCI.)

To use this feature, simply start Sauce Connect using the -i flag (or --tunnel-identifier) and provide your own unique identifier string. Once the tunnel is up and running, any tests that you want going through this tunnel will need to provide the correct identifier using the tunnel-identifier desired capability.

You can find more info about this Desired Capability, in our job customizations documentation.

How can I keep Sauce Connect fresh?

Connect handles a lot of traffic for heavy testers. Here is one way to keep it 'fresh' to avoid leakages and freezes.

First write a loop that will make sure of starting Sauce Connect every time it gets killed or crashes:

$ while :; do killall java; sleep 30; java -jar Sauce-Connect.jar YOUR-SAUCE-USERNAME YOUR-SAUCE-API-KEY; done

Then write a cron task that will kill Sauce Connect on regular basis:

$ crontab -e
00 00 * * * killall java

This will kill Sauce Connect every day at 12am, but can be modified to behave differently depending on your requirements. To preserve Java processes that are already running, you can also isolate the restart loop to Sauce Connect.

How can I protect the information I send from my scripts?

Sauce Connect automatically creates a secure and reliable connection between our cloud browsers and your web server, for all the tests running under your Sauce account. You can also do this for communication between your test scripts and Sauce Labs, by relaying commands through the Connect tunnel.

Just point your script's command_executor to the IP address of the machine running Sauce Connect; for example, replace "ondemand.saucelabs.com:80" with "localhost:4445".
Then, start Sauce Connect with the -P flag to change the port (as described below).

Can I use Sauce Connect in addition to Browsermob Proxy?

You can daisy chain Sauce Connect with other proxy servers, including Browsermob Proxy.
To do this, start Connect with the -p flag and provide the location of your proxy instance. All traffic from our browsers will be sent through it:

java -jar Sauce-Connect.jar YOUR-SAUCE-USERNAME YOUR-SAUCE-API-KEY -p localhost:9091

How can I limit network traffic that might slow down performance?

Connect enables you to filter network traffic from sources you specify (such as Google Analytics), using the --fast-fail-regexps parameter:

java -jar Sauce-Connect.jar YOUR-SAUCE-USERNAME YOUR-SAUCE-API-KEY --fast-fail-regexps "google.com,saucelabs.com,favicon.ico"

You can use a single regular expression, or include multiple options in a comma-separated list.

What option flags are available when starting Sauce Connect?

These options are supported for Sauce-Connect.jar:

usage: java -jar Sauce-Connect.jar USERNAME API_KEY [OPTIONS]
 -D,--direct-domains        Comma-separated list of
                                             domains. Requests whose host
                                             matches one of these will be
                                             relayed directly through the
                                             internet, instead of through
                                             the tunnel.
 -d,--debug                                  Enable verbose debugging.
 -f,--readyfile                        Ready file that will be
                                             touched when tunnel is ready.
 -F,--fast-fail-regexps     Comma-separated list of
                                             regular expressions. Requests
                                             matching one of these will
                                             get dropped instantly and
                                             will not go through the
                                             tunnel.
 -h,--help                                   Display this help text.
 -i,--tunnel-identifier    Don't automatically assign
                                             jobs to this tunnel. Jobs
                                             will use it only by
                                             explicitly providing the
                                             right identifier.
 -l,--logfile 
 -P,--se-port                          Port in which Sauce Connect's
                                             Selenium relay will listen
                                             for requests. Selenium
                                             commands reaching Connect on
                                             this port will be relayed to
                                             Sauce Labs securely and
                                             reliably through Connect's
                                             tunnel.
 -p,--proxy             Proxy host and port that
                                             Sauce Connect should use to
                                             send connections from
                                             browsers in the Sauce Labs
                                             cloud to be able to access
                                             the AUT.
 -s,--shared-tunnel                          Let sub-accounts of the
                                             tunnel owner use the tunnel
                                             if requested.
 -S,--squid-opts              Configuration used for the
                                             Squid reverse proxy in our
                                             end. Use only if directed to
                                             do so by Sauce Labs support.
 -v,--version                                Print the version and exit.
 -x,--rest-url                          Advanced feature: Connect to
                                             Sauce REST API at alternative
                                             URL. Use only if directed to
                                             do so by Sauce Labs support.

Troubleshooting

Web traffic is slow after using Sauce Connect

Whether or not you're currently running Connect, you may experience latency because of an improperly closed session. Make sure to always close Sauce Connect in a clean fashion, such as Ctrl+C, to allow it to complete its shutdown processes. This typically takes only a few seconds. If the session is killed by turning off the terminal (or other instant methods), Connect is prevented from reporting back and closing the tunnel on our end.

You can resolve this issue by manually closing any open tunnels, from the View Tunnels section of your account page. Once you shut down the Sauce side of the tunnel, performance should improve as traffic goes through the public Internet.

Unable to run tests through Sauce Connect: Test server not accessible through tunnel

When this issue happens, it is generally caused by the web server that the tests are trying to hit not being accessible to the machine in which Connect is running at the time, or having a different address than the one being used. Firewall rules blocking it are a possibility.

To confirm this, we recommend that you try opening any web browser in the local machine that Connect is running on, and use the same address that your tests use to access the website. Confirm that the web server is accessible locally and online during the tests.

Accessing applications on localhost

Sauce Connect proxies these commonly-used localhost ports:

80, 443, 888, 2000, 2001, 2020, 2222, 2310, 3000, 3001, 3030, 3333, 4000, 4001, 4040, 4502, 4503, 5000, 5001, 5050, 5555, 6000, 6001, 6060, 6666, 7000, 7070, 7777, 8000, 8001, 8003, 8031, 8080, 8081, 8888, 9000, 9001, 9080, 9090, 9999, 49221

So when you use Connect, your local web apps are available to test just as if the cloud were inside your local machine. Easy!

Do you need a different port? Please let us know! We do our best to support ports that will be useful for many customers, such as those used by popular frameworks.

SSL errors

If you see SSL errors in your test videos or screenshots, try adding -Dhttps.protocols="SSLv3,SSLv2Hello" to your Sauce Connect command line in the following way:

java -jar -Dhttps.protocols='SSLv3,SSLv2Hello' Sauce-Connect.jar USERNAME API-KEY

Some users see an SSL handshake exception while connecting to Sauce, including this text:

javax.net.ssl.SSLHandshakeException:
sun.security.validator.ValidatorException: PKIX path validation failed:
java.security.cert.CertPathValidatorException

This error is most commonly caused by the version of Java in your path. Make sure that the Java version being used by Connect is an official, stable Oracle release.

Permission errors

Sauce Connect's log file ( sauce_connect.log ) will be created in the present working directory when you run the command to launch Connect for this reason, that directory must be writable or you'll get an error.

Known limitations

Firefox versions 12 and newer must be tested with Selenium 2 (WebDriver). This is because Selenium 1 (RC), when paired with Sauce Connect, requires browsers to proxy traffic through Selenium, which recent Firefox versions don't support. You can prevent this issue by using Firefox versions older than 12, or by testing these versions without Connect, or by running tests through WebDriver (which is better supported by the Selenium project).

We're working to make Sauce Connect compatible with WebSockets; in the meantime, sites with this feature can't be tested through Sauce Connect. However, you can still test any such sites that are publicly available with vanilla Sauce.

Want more?

If you'd like to dig deeper, feel free to check out our help forums, or email us directly at help@saucelabs.com.

Security & Tips

What is exposed when using Sauce Connect?

As much (or as little) as you allow. To ensure the highest level of security, we recommend putting Sauce Connect on a dedicated server to precisely control, via firewall, the exact machines, subnet, and port combinations it can see. Sauce Connect only transmits encrypted traffic to a dedicated receiver in the Sauce Labs cloud, and all connections are secured via industry-standard SSL. No other Sauce Labs customers can see or access unencrypted transmissions, or control execution of tests.

Does Sauce share Connect tunnels?

No, never. Each time you use the Sauce cloud, a pristine VM is spun up solely for your instance of Connect. Pristine means both Tunnel and Browser VMs with no history, no extraneous plug-ins and no hacks (except for the ones you put in your sites).

Don't limit external communication on port 443

Sauce Connect uses port 443 (SSL) to send and receive encrypted traffic from and to our cloud. It's important that nothing is blocking Connect from making an outgoing connection over port 443 to both the Sauce cloud and saucelabs.com.

Server spec recommendations

A standard development machine is enough to run a temporary Sauce Connect instance and use our service with 30 tests in parallel or less. However, as soon as your usage increases and you run more tests on a regular basis, we recommend using a server-like box to host Sauce Connect more reliably.
Our spec requirements are not as stringent, but 4Ghz CPU and 8G RAM are good ballpark numbers.