Docs sauce connect
Test servers inside your firewall from the Sauce Labs Cloud.
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
--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
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:
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:
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:
Connectivity issues when using Sauce Connect
If you find you can't load a page that should be accessible, check the age of your Sauce Connect tunnel. After transmitting a large amount of data, the tunnel may eventually stagnate. In that case, restarting Connect should resolve the issue. (More info)
Also, check to ensure that you aren't using the "avoid-proxy" flag in your scripts. Since Connect usually requires use of the Selenium proxy, this can cause unexpected problems in your test run.
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:
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.
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:
Some users see an SSL handshake exception while connecting to Sauce, including this text:
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.
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.
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.
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.
What is Sauce Connect?
Sauce Connect securely proxies browser traffic between Sauce Labs' cloud-based VMs and your local servers. Connect uses ports 443 and 80 for communication with Sauce's cloud. Most companies allow this without special exceptions.
These vary depending on the number of parallel tests you plan to run. Here are some samples based on simultaneous test volume:
|30 tests||4 Gb||4 gHz|
|Use your dev machine|
|100 tests||8 Gb||4 gHz|
|+ use a dedicated Connect server|
|+ set uLimit to 8192|
For increased reliability and security,
use a dedicated server.
How is Sauce Connect secured?
Sauce Connect uses industry-standard SSL encryption for all connections.