Skip to main content

Reach a private site from TestingBot

Your tests run on TestingBot's browsers and devices, not on your network. If the site under test is not public, those machines need a way in. There are three: let TestingBot's IP addresses through your firewall, run TestingBot Tunnel, or run the tunnel through your corporate proxy. This page helps you pick one and lists the firewall rules each needs.

Which option?

Your situation Use
The site has a public address, but a firewall or web server only lets known IP addresses in Allowlist TestingBot's IPs
The site runs on localhost, uses an internal hostname, or is on a network you cannot open to the internet TestingBot Tunnel
You are not allowed to add inbound firewall rules TestingBot Tunnel (outbound only)
The machine running the tunnel can only reach the internet through a proxy Tunnel with --proxy / --proxy-testingbot

The options do not combine: a request that goes through the tunnel leaves from the machine running the tunnel, so the site sees your own network, not a TestingBot address. If you use the tunnel, you do not need to allowlist anything.

Allowlist TestingBot's IP addresses

Add TestingBot's public addresses to the firewall, load balancer or web server rule in front of your site. Requests from TestingBot sessions then get through, and nothing needs to run on your side.

The current list is on the grid configuration page. It is also available as a JSON array, without authentication:

curl -s https://api.testingbot.com/v1/configuration/ip-ranges
  • Allowlist every address. The list is one set for all TestingBot sessions and is not split by browser, emulator, simulator or real device. A test can run on any of these machines, so a partial list gives tests that pass on one run and fail on the next.
  • Fetch it, don't copy it. Addresses are added as capacity grows. Pull the list from the API in your firewall automation, or check it again when tests that used to pass start getting blocked.
  • Geolocation testing uses other addresses. With the geoCountryCode capability, traffic leaves from the country's address in the geolocation IP list. Add those too if you use it.
  • The addresses are shared. They belong to TestingBot's machines, and those machines run other customers' sessions too. An allowlist keeps the general public out, but it is not a password. Keep your own login or authentication on anything sensitive, or use the tunnel instead.
  • It cannot reach what is not routable. localhost, internal DNS names and private IP ranges are not reachable from the internet, so no allowlist helps. Use the tunnel for those.

TestingBot Tunnel

The tunnel runs on a machine inside your network and opens an outbound, encrypted connection to a tunnel server that TestingBot starts for you. The cloud browser or device sends its requests through that server back to the tunnel, which fetches the page from inside your network.

export TESTINGBOT_KEY=... TESTINGBOT_SECRET=...
java -jar testingbot-tunnel.jar
  • It reaches anything the tunnel machine can reach: localhost (use local.testingbot.com in the test, see the FAQ), internal hostnames, and private IP ranges.
  • One tunnel serves desktop browsers, emulators, simulators and real devices. See the FAQ.
  • It needs no inbound ports, only outbound port 443.
  • Restrict what the cloud may reach through it with --allow-hosts.

Start with the quickstart.

Tunnel behind a corporate proxy

Where the tunnel machine can only reach the internet through a proxy, the tunnel can send its own connection to TestingBot through that proxy too.

Option What goes through it
--proxy host:port Everything, unless --proxy-testingbot is set: test traffic to your sites, and the tunnel's own connections to the TestingBot API and tunnel server. Accepts host:port, http://host:port or socks5://host:port.
--proxy-userpwd user:pwd Credentials for --proxy. Prefer the TESTINGBOT_PROXY_USERPWD environment variable.
--proxy-testingbot host:port Only the tunnel's connections to TestingBot (the API and the tunnel server). Test traffic keeps using --proxy, or goes direct. Same forms as --proxy.
--proxy-testingbot-userpwd user:pwd Credentials for --proxy-testingbot. Not taken from --proxy-userpwd.
--pac-local file-or-url A PAC file that picks direct or proxy per destination for the tunnel's outgoing traffic.

The common split: internal sites are reachable directly (or through an internal proxy), while the internet is only reachable through an egress proxy. Send only TestingBot's traffic to the egress proxy:

export TESTINGBOT_PROXY_TESTINGBOT_USERPWD=user:password
java -jar testingbot-tunnel.jar --proxy-testingbot corp-egress.example.com:3128

The Selenium commands your tests send to the tunnel's local port (localhost:4445 by default) travel inside the tunnel's own connection, not through --proxy. Kerberos proxies, TLS-intercepting proxies and PAC details are on the upstream proxy page.

Outbound firewall rules

What the machine running your tests, or the tunnel, must be able to reach. None of these need inbound rules.

Destination Port Needed by
hub.testingbot.com 443 Selenium and Appium tests that connect to the hub directly (HTTPS). Not needed for tests that connect through the tunnel's local port.
cloud.testingbot.com 443 Playwright and Puppeteer (wss://)
api.testingbot.com 443 TestingBot Tunnel (HTTPS), to start and stop its tunnel server. Also the REST API and app uploads.
Your tunnel server 443 TestingBot Tunnel. The connection is SSH, on port 443.
The tunnel server is an IP address, and the protocol is SSH

The API assigns each tunnel its own server when the tunnel starts and returns it as an IP address, which the tunnel connects to directly. A firewall rule that only allows *.testingbot.com by hostname will not match it. And although the port is 443, the connection is SSH, not TLS: a firewall or proxy that only lets TLS out on 443 blocks it. If either applies, allow outbound SSH on port 443, or send the tunnel's connections through a proxy that permits CONNECT to port 443 with --proxy-testingbot.

Check your firewall

Run these on the machine that will run your tests or the tunnel. Each should print 200.

# TestingBot API (used by the tunnel to start)
curl -sS -o /dev/null -w "%{http_code}\n" https://api.testingbot.com/v1/browsers

# Selenium / Appium hub
curl -sS -o /dev/null -w "%{http_code}\n" https://hub.testingbot.com/wd/hub/status

# Playwright / Puppeteer endpoint
curl -sS -o /dev/null -w "%{http_code}\n" https://cloud.testingbot.com/

Behind a proxy, add the same proxy the tunnel will use, for example curl -x http://corp-egress.example.com:3128 .... A timeout or Could not resolve host means the firewall or DNS blocks it; a 403 from the proxy usually means the proxy's own allowlist does.

The tunnel server's address is only known once a tunnel starts. If the tunnel starts but never reports You may start your tests, find the address with GET /v1/tunnel/list and test the port:

curl -s -u "$TESTINGBOT_KEY:$TESTINGBOT_SECRET" https://api.testingbot.com/v1/tunnel/list
nc -vz TUNNEL_SERVER_IP 443

Finally, run the tunnel with --doctor together with your proxy options. It checks that it can reach TestingBot, that its local ports are free, and the proxy, certificate and Kerberos settings. See troubleshooting.

Was this page helpful?
Last updated