Route through an upstream proxy

On many networks the only route out is a proxy. The tunnel can send its own connection to TestingBot, and the traffic it carries for your tests, through an upstream HTTP or SOCKS5 proxy. It can also use a different proxy per destination. Common uses are corporate proxies and GeoIP proxies for region-specific testing.

Basic configuration

Pass the proxy with --proxy, and credentials with --proxy-userpwd.

java -jar testingbot-tunnel.jar --proxy <proxy-host:proxy-port> --proxy-userpwd <username>:<password>

Form	Proxy type
host:port	HTTP proxy
http://host:port	HTTP proxy
socks5://host:port	SOCKS5 proxy, with optional username and password

Unless you set --proxy-testingbot, the proxy carries everything: the browser's requests to your sites, HTTPS CONNECT tunnels, WebSocket upgrades, and the tunnel's own connection to TestingBot.

Corporate proxies

Forward both the control channel to *.testingbot.com and the test traffic through your authenticated proxy.

Export TESTINGBOT_PROXY_USERPWD instead of passing -z on the command line so the credentials never appear in the process list.

export TESTINGBOT_PROXY_USERPWD=alice:hunter2
java -jar testingbot-tunnel.jar --proxy corp-proxy.example.com:8080

Proxy needs Kerberos instead of a password? Add --proxy-auth-scheme negotiate. See Kerberos proxies.

A separate proxy for TestingBot

Where egress is filtered by destination, the proxy allowed out to the internet is often not the one that reaches your internal test targets. --proxy-testingbot gives TestingBot's own traffic, the API and the tunnel's SSH connection, a different proxy from the one test traffic uses.

java -jar testingbot-tunnel.jar \
  --proxy 10.0.0.9:8080 \
  --proxy-testingbot corp-egress:3128 --proxy-testingbot-userpwd user:password

Credentials are deliberately not shared: --proxy-userpwd belongs to one proxy operator and is not sent to another. Give each proxy its own.

Routing with a PAC file

--pac-local points the tunnel at a proxy auto-config file and lets it decide, per destination, whether to go direct or through a proxy. This is how your browser already handles a corporate network, applied to the tunnel.

java -jar testingbot-tunnel.jar --pac-local /etc/corp.pac
java -jar testingbot-tunnel.jar --pac-local https://corp.example/proxy.pac

Check what a file decides for a URL before relying on it:

java -jar testingbot-tunnel.jar --pac-local corp.pac --pac-test https://internal.corp/page

Use https:// or a local file. A PAC file decides where traffic goes. Fetched over plain http://, it is whatever the network says it is, so a plain http:// URL is refused unless you pin its contents with --pac-local-sha256. Redirects are refused rather than followed.
A purpose-built interpreter, no JavaScript engine. It supports what PAC files use: functions, variables, conditionals, loops, the usual operators, and the standard helpers (isPlainHostName, dnsDomainIs, shExpMatch, isInNet, dnsResolve, myIpAddress and the date and time predicates).
Unsupported syntax is reported with its line number, rather than guessed at. Object literals, regular expressions and new are not supported. A misread PAC file would silently send traffic to the wrong place.
No credentials for PAC-chosen proxies. A proxy named only by the PAC file does not receive --proxy-userpwd. The tunnel logs that it withheld them.

java -jar testingbot-tunnel.jar --pac-local http://wpad.corp/proxy.pac \
  --pac-local-sha256 3b1f...64-hex-characters

PAC for the remote browser

--pac is a different option: it tells the cloud browser which PAC URL to use. It does not change where the tunnel itself sends traffic.

java -jar testingbot-tunnel.jar --pac https://corp.example.com/proxy.pac

Option	Evaluated by	Decides
--pac-local	The tunnel, on your machine	Where the tunnel sends its own outgoing traffic
--pac	The remote browser	Which proxy the cloud browser uses

TLS-intercepting proxies

If the proxy intercepts TLS and re-signs it with an internal certificate authority, Java will not trust it and the tunnel cannot register itself. Point it at the authority.

java -jar testingbot-tunnel.jar --proxy proxy.corp:8080 --cacert-file /etc/ssl/corp-ca.pem

The certificate is added to the platform's trust store rather than replacing it. --doctor prints the subjects it loaded. See SSL bumping and certificates.

WebSockets through a proxy

--ws-proxy-mode controls how a ws:// upgrade crosses --proxy.

Mode	Behaviour
connect	Default. Ask the proxy to open a tunnel with `CONNECT` and upgrade inside it. This is what RFC 6455 specifies and what browsers do.
get	Send the upgrade to the proxy as an ordinary request. For proxies that forward `Upgrade` but only allow `CONNECT` to port 443.

wss:// is always a CONNECT, so this option does not affect it.

Things to know

Run --doctor with your proxy options. It tests the route out and, for Kerberos, every step of the Negotiate chain.
A failing proxy shows up in the cloud browser with an X-TestingBot-Error of upstream-proxy-unreachable, upstream-proxy-auth-failed or upstream-proxy-refused. See reading errors.
WebSocket and SSE traffic requires --nobump --nocache in addition to the proxy flags.
See the CLI reference for every proxy-related flag.