The Situation

The Sauce Connect proxy setup is for situations in which there is a proxy server between the Internet and the machine hosting Sauce Connect, or between the machine hosting Sauce Connect and the machine hosting the website you want to test. In these cases you will want to use the Sauce Connect proxy commands to configure the proxy host and port that Sauce Connect can use to either reach the Internet or the site you want to test. 

Network Diagrams

If you use a Man-in-the-Middle proxy to monitor network traffic, it must be configured to allow the TLS connection and proprietary protocol that Sauce Connect uses to communicate with the Sauce Labs virtual machines that are running your tests. If it will allow only HTTP or HTTPS sessions, it will drop the inbound Sauce Connect connection. Check out Sauce Connect Start Up and Tear Down Process for more information about how Sauce Connect starts up and maintains the connection with the Sauce Labs browser cloud.  

Internet Control/Transaction Monitoring with a Proxy Configuration

You may have a network configuration in which you use a proxy to control the flow of traffic from your internal network to the external Internet, either as a means of adding security to your network, or whitelisting or blacklisting certain sites. In this situation you could set up Sauce Connect behind a proxy like BrowserMob, which records all traffic that passes through it, and which can later provide a history of that traffic. 

Proxied Site Under Test (SUT)

In this configuration the SUT is behind a proxy, to allow even more control over traffic before it reaches the SUT.  Typical this setup is used to control access to the SUT by means of IP whitelisting, or requiring a username and password to access the proxy.

You now have three options for proxy configuration:

Automatic Proxy Configuration

As of Sauce Connect 4.3.1, proxies and PAC settings are autoconfigured based on the settings of the operating system on the machine where it is installed.

You can disable automatic proxy detection with the command line option  ./sc -z --no-autodetect.

Command Line Configuration

If automatic proxy configuration fails, you need to override the settings, or you need to enable proxies through a test script, there are several command-line options that you can use to configure proxies manually

Fundamentally, Sauce Connect makes two separate outbound connections for two separate purposes. The first, which -p, --proxy <host:port> uses, is a lightweight connection to our REST API that simply tells our servers basic information about the status of Sauce Connect's status (for example, starting up, ready, stopping).

The second connection is to the actual tunnel virtual machine (VM) created for your Sauce Connect instance. Enabling the -T, --proxy-tunnel flag will cause some proxy specified with -p, --proxy to be used for this connection as well. You should try to avoid using a proxy for this connection, since it is already TLS secured, and a large volume of data tends to go over this connection. Adding another step in the middle, in the form of a proxy, can hinder test performance.

Ideally you should only need to use -p, --proxy <host:port> (and perhaps -w, --proxy-userpwd <user:pwd> for credentials), but -T, --proxy-tunnel is available if your network doesn't allow outgoing connections on port 443. If your tests are slow, you may want to ask your network administrator about making an exception for this connection.

BrowserMob Proxy Configuration

You can use BrowserMob Proxy with Sauce Connect 4.2 and higher by using the Sauce Connect PAC feature. 

Since BrowserMob bumps SSL connections, and Sauce Connect 4 verifies the certificate when connecting to the REST API, that means the --proxy option can't be used with a BrowserMob proxy. Sauce Connect will complain that the certificate received from the REST endpoint is invalid.

To choose a proxy in a dynamic fashion, however, you can create a PAC file that matches the REST and tunnel VM hostnames, and uses the local BrowserMob proxy for everything else.

  1. Start BrowserMob Proxy.

    $ ./browsermob-proxy --port 9000

     

  2. Start another terminal and create a proxy instance in BrowserMob.

    $ curl -X POST http://localhost:9000/proxy
    {"port":9091}

     

  3. Create a file, browsermob.js, with this content. 
    This is what you will pass into Sauce Connect 4.

    function FindProxyForURL(url, host) {
        if (shExpMatch(host, "*.miso.saucelabs.com") ||
            shExpMatch(host, "*.api.testobject.com") ||
            shExpMatch(host, "*.saucelabs.com") ||
    		shExpMatch(host, "saucelabs.com")) {
            // KGP and REST connections. Another proxy can also be specified.
            return "DIRECT";
        }
    
        // Test HTTP traffic, route it through the local BrowserMob proxy.
        return "PROXY localhost:9091";
    }

     

  4. Copy the file to the same directory as Sauce Connect 4, and start Sauce Connect 4.

    $ ./sc -v --pac file://$(pwd)/browsermob.js

    Sauce Connect 4 will print the proxy used for REST and the tunnel VM connection, which should be Using no proxy for connecting to Sauce Labs REST API and Using no proxy for connecting to tunnel VM if their hostnames are configured with DIRECT access.

WonderProxy

You can use WonderProxy for GeoIP website testing with Sauce Connect. Check out the step-by-step setup guide on the WonderProxy website.

After Setting Up Sauce Connect

Command Line Examples

In its simplest form, Sauce Connect can be started from the command line with these commands.

#On Linux or Mac OSX you would use the following
>./sc -u YOUR_USERNAME -k YOUR_ACCESS_KEY --proxy host:port --proxy-tunnel
 
#On windows you would use the following
>sc.exe -u YOUR_USERNAME -k YOUR_ACCESS_KEY --proxy host:port --proxy-tunnel

Starting Sauce Connect Programmatically

To start Sauce Connect programmatically, there are many options, such as launching it via Maven when using Java. The Sauce Connect Maven plugin will do this for you automatically, and you can also check out an example of how to set this up in a testing script.