The Sauce Labs Cookbook


Analytics

Front End Performance Testing

Sauce Headless

The Sauce Labs Cookbook

Utensils

More Info

Page tree
Skip to end of metadata
Go to start of metadata

Beginning with version 4.5.0 some of the command line arguments can be provided through a config file or an environment variable. The order of precedence when the same argument is provided through multiple methods is as follows, methods to the left have higher precedence.

Command Line Argument > Config File > Environment Variable


Flag (Short)Flag (Long)

Description

-u

 --user <username>

Instead of explicit <username> you can also use the environment variable SAUCE_USERNAME on the command line.

-k
 --api-key <api-key>

Instead of explicit <api-key> you can also use the environment variable SAUCE_ACCESS_KEY on the command line.

-c
 --config-file <path>

Version 4.5.0 and above.

Local path to a YAML file containing Sauce Connect configuration. Please refer to the following sample YAML file for more information.

The below line shows the order of precedence when the same argument is provided through multiple methods. Methods to the left have higher precedence.

Command Line Argument > Config File > Environment Variable

It is recommended to use a configuration file than command line arguments in production environments for the following reasons:

  • Ability to track configuration changes.
  • Easier to manage tunnel-domains and direct-domains options that can get very long.
  • Secure Sauce Connect credentials with tighter access control on the config file
-B
 --no-ssl-bump-domains <...>

Comma-separated list of domains. Requests including hosts that matches one of these domains will not be SSL re-encrypted. See the section on SSL Bumping Enabled by Default in the Troubleshooting Sauce Connect topic for more information about situations in which you would want to use this command.

Formatting Domains

  • Make sure your comma-separated list of domains doesn't include any spaces. For example, mydomain.com,saucelabs.com,mysite.com, instead of mydomain.com, saucelabs.com, mysite.com
  • Use only the domain name, you don't need to precede it with http: or https:
  • Prefix a domain name with "*." or simply "." to match all its subdomains. For example, you could refer to both wiki.saucelabs.com and my.saucelabs.com with "*.saucelabs.com" or ".saucelabs.com". Enclose the argument in quotes to prevent shell expansion of asterisk.
  • If you don't want any domains to be SSL re-encrypted, you can specify all with the argument(i.e. -B all or --no-ssl-bump-domains all)
  • WebSockets don't work with SSL bumping. SSL Bumping should be disabled for WebSocket domains.

HTTP Header Injection is disabled for all HTTPS domains passed to --no-ssl-bump-domains argument.

-N
 --no-proxy-caching

Disable caching in Sauce Connect. All requests will be sent through the tunnel.

-M
 --max-missed-acks <...>

The maximum amount of keepalive acks that can be missed before the client will trigger a reconnect. The default is 30.

-D
 --direct-domains <...>

Comma-separated list of domains. Requests including hosts that matches one of these domains will be relayed directly through the Internet, instead of through the Sauce Connect tunnel.

Formatting Domains

  • Make sure your comma-separated list of domains doesn't include any spaces. For example, mydomain.com,saucelabs.com,mysite.com, instead of mydomain.com, saucelabs.com, mysite.com
  • Use only the domain name, you don't need to precede it with http: or https:
  • Prefix a domain name with "*." or simply "." to match all its subdomains. For example, you could refer to both wiki.saucelabs.com and my.saucelabs.com with "*.saucelabs.com" or ".saucelabs.com". Enclose the argument in quotes to prevent shell expansion of asterisk.
-t
 --tunnel-domains <...>

Inverse of --direct-domains. Overrides --direct-domains. Only requests for domains in this list will be sent through the Sauce Connect tunnel.

Formatting Domains

  • Make sure your comma-separated list of domains doesn't include any spaces. For example, mydomain.com,saucelabs.com,mysite.com, instead of mydomain.com, saucelabs.com, mysite.com
  • Use only the domain name, you don't need to precede it with http: or https:
  • Prefix a domain name with "*." or simply "." to match all its subdomains. For example, you could refer to both wiki.saucelabs.com and my.saucelabs.com with "*.saucelabs.com" or ".saucelabs.com". Enclose the argument in quotes to prevent shell expansion of asterisk.
-v
 --verbose

Enable verbose debugging. -vv will output HTTP headers and KGP logs. From version 4.4.3, -v will also output HTTP headers.

Running Sauce Connect Proxy with the very verbose -vv option is system-resource demanding and will adversely affect Sauce Connect Proxy performance. This option is meant for troubleshooting only, not for long-term use and should not be used in production.


-F
 --fast-fail-regexps <...>

Comma-separated list of regular expressions. Requests with URLs matching one of these will get dropped instantly and will not go through the tunnel. See the question How Do I Use Sauce Connect to Test Graceful Degradation in the Sauce Connect FAQs for an example of how you would use this command to test for application or site degradation based on missing assets or resources.

-i
 --tunnel-identifier <id>

Assign <id> to this Sauce Connect instance. Future jobs will use this tunnel only when explicitly specified by the tunnel-identifier DesiredCapability in a Selenium client. Check out the topic Using Multiple Sauce Connect Tunnels for information on using tunnel-identifier to run multiple Sauce Connect tunnels simultaneously. Test Configuration Options contains more information about the syntax for setting tunnel-identifier as a DesiredCapability. Note that <id> must be ASCII.

-l
 --logfile <file>

Capture the Sauce Connect logs in <file>. If a path is not specified in <file>, the default location of the <file> is the same location where the Sauce Connect executable can be found on your machine.

-P
 --se-port <port>

Port on which Sauce Connect's Selenium relay will listen for requests. Selenium commands reaching Sauce Connect on this port will be relayed to Sauce Labs securely and reliably through Sauce Connect's tunnel. Defaults to 4445.

-p
 --proxy <host:port>

Proxy host and port that Sauce Connect should use to connect to the Sauce Labs cloud. See Sauce Connect Proxy with an Additional Proxy Setup for more information about using Sauce Connect with proxies.

-w
 --proxy-userpwd <user:pwd>

Username and password sent via basic authentication required to access the proxy configured with -p. See   Sauce Connect Proxy with an Additional Proxy Setup for more information about using Sauce Connect with proxies. 


 --pac <url>

Proxy autoconfiguration. Can be a http(s) or local file:// URL. See  Sauce Connect Proxy with an Additional Proxy Setup for more information about using Sauce Connect with proxies.

Absolute paths are required when specifying a local PAC file (EG. file:///Users/Andrew/Desktop/MyPac.pac).

-T
 --proxy-tunnel

Use the proxy configured with -p for the tunnel connection.See  Sauce Connect Proxy with an Additional Proxy Setup for more information about using Sauce Connect with proxies.

For Sauce Connect 4.5.3 and up, you must use this option if you use a PAC file and you have Sauce Labs DNS names in the PAC file.

-s
 --shared-tunnel

Allows sub-accounts of the tunnel owner to use the tunnel. See the question Can I Reuse a Tunnel Between Multiple Accounts? in the Sauce Connect FAQs for more information on using this command.

-x
 --rest-url <arg>

By default Sauce Connect connects to "US virtual desktop and device cloud", use this option if you need to connect to a different Sauce Labs cloud.

-f
 --readyfile

File that will be touched to indicate when the tunnel is ready.

-a
 --auth <host:port:user:pwd>

Perform basic authentication when a URL on <host:port> asks for a username and password. This option can be used multiple times. Using --auth with Sauce Connect Proxy includes an example.

HTTP Header Injection is disabled for SSL domains that are not re-encrypted by Sauce Connect, which means performing basic authentication in this way is disabled for all HTTPS domains passed to --no-ssl-bump-domains argument.
-z
 --log-stats <seconds>

Log statistics about HTTP traffic every <seconds>. Information includes bytes transmitted, requests made, and responses received.


 --max-logsize <bytes>

Rotate logfile after reaching <bytes> size. Disabled by default.


 --doctor

Perform checks to detect possible misconfiguration or problems. Check out Troubleshooting Sauce Connect Proxy with --doctor for more information about the errors that --doctor will detect and how to resolve them. 


 --no-autodetect

Disable the autodetection of proxy settings.


 --version

Display version information and exit.

-r
 --reconnect <seconds>

Maximum time in seconds to wait between tunnel reconnect attempts.

-X
 --scproxy-port <port>

Port to use for the built-in HTTP proxy.


 --cainfo <cainfo file>

CA certificate bundle to use for verifying REST connections.


 --capath <capath dir>

Directory of CA certs to use for verifying REST connections.


 --no-cert-verify

Disable certificate verification for REST connections.

Sauce Developers Only

This flag is intended to be used by Sauce Connect developers only.


--tunnel-cert public

Supported only in Sauce Connect 4.5.4 and above. Require that the certificates on the Sauce Labs internal tunnel Virtual Machine be signed by a Certificate Authority instead of self-signed certificates.

--scproxy-read-limit <X>
Rate limit reads in scproxy to X bytes per second. This option can be used to adjust local network transfer rate in order not to overload the tunnel connection.

--scproxy-write-limit <X>
Rate limit writes in scproxy to X bytes per second. This option can be used to adjust local network transfer rate in order not to overload the tunnel connection.
-o

--output-config

Write all configuration options as JSON to stdout. This flag is used by our Jenkins plugin and is not intended to be used by end-users.

--daemonize

Go into the background after starting up.

Depreciated in 4.4.0

--daemonize is deprecated in Sauce Connect Proxy from version 4.4.0 onwards. This KB article in the Sauce Labs support portal has more information:

https://support.saucelabs.com/hc/en-us/articles/115002314128-No-daemonize-Option-in-Sauce-Connect-Proxy-4-4-0


--dns <server[,server..]>

Use specified name server. To specify multiple servers, separate them with a comma. Use IP addresses, optionally with a port number, the two separated by a colon. Example: --dns 8.8.8.8,8.8.4.4:53

--no-remove-colliding-tunnels

Don't remove identified tunnels with the same name, or any other default tunnels if this is a default tunnel. Jobs will be distributed between these tunnels, enabling load balancing and high availability. By default, colliding tunnels will be removed when Sauce Connect is starting up.


--wait-tunnel-shutdown

When shutting down, wait for all active jobs using the tunnel to finish. By default, Sauce Connect will force the shutdown of the tunnel even when there are active jobs.

Deprecated in 4.4.5

--wait-tunnel-shutdown is deprecated in Sauce Connect Proxy from version 4.4.5 onwards. Going forward, the behavior will be that tunnels wait for all tests to complete before shutting down the tunnel.

-d

--pidfile <file>

File to write Sauce Connect's process ID into. Useful for programmatically stopping Sauce Connect.

Sauce Connect Proxy makes a best effort but cannot guarantee that the pidfile will be removed when shutting down Sauce Connect Proxy. With that in mind, relying on the pidfile as a means to monitor Sauce Connect Proxy is not supported.


--metrics-address=address

host:port for the internal web server used to expose client side metrics. (default: localhost:8888)

-h

--help

Display the help text.

 

--extra-info '{"inject_job_id": true}'

Injects job id and tunnel id as HTTP request headers.

HTTP Header Injection is disabled for SSL domains that are not re-encrypted by Sauce Connect, in otherwords Header Injection is disabled for all HTTPS domains passed to --no-ssl-bump-domains argument.