Percy is a visual regression testing tool that takes screenshots of your web pages and compares them against baselines to catch unintended UI changes. When your staging or development site sits behind a VPN or firewall, Percy’s cloud browsers cannot reach it directly, so builds fail with timeout or connection errors. This guide walks you through the two reliable ways to test such sites: using Percy’s proxy agent (for VPNs) and using a tunnel like ngrok or localtunnel (for firewalls that block inbound connections). You’ll also learn how to configure your CI pipeline and debug common issues.
What You’ll Need
- A Percy account and a project token (found in Percy’s project settings).
- Node.js (v14 or later) installed on the machine that runs the tests.
- Access to the site you want to test—either from your local machine or from a CI runner that is inside the VPN/firewall.
- For the proxy agent method: the ability to run a long-lived process that can reach both the site and Percy’s API.
- For the tunnel method: a tunnel client like
ngrokorlocaltunnelinstalled, or the ability to install it.
Step-by-Step
Method 1: Using Percy Proxy Agent (for VPNs)
- Install the Percy CLI and agent. In your project directory, run
npm install --save-dev @percy/cli. This installs the Percy command-line tool that includes the proxy agent. - Set your project token. Export your Percy token as an environment variable:
export PERCY_TOKEN=your_token_here. You can find this token in your Percy project settings. - Start the proxy agent. Run
percy agent:startin your terminal. This starts a local proxy server (default port 5338) that will forward requests from Percy’s cloud browsers to your site. Keep this terminal open. - Configure your test runner to use the proxy. In your Percy configuration file (e.g.,
percy.config.jsor via CLI flags), set theagentoption to point to the proxy. For example, in yourpercy.config.js:module.exports = { agent: { port: 5338 } };Or pass
--agent-port=5338when running Percy commands. - Run your visual tests. Execute your normal Percy test command (e.g.,
percy exec -- npm test). Percy’s cloud browsers will now route screenshot requests through the proxy agent, which fetches the page from behind your VPN. - Stop the agent. After tests complete, press
Ctrl+Cin the agent terminal to stop it.
Method 2: Using a Tunnel (for Firewalls)
- Install a tunnel client. If you don’t have one, install ngrok globally:
npm install -g ngrokor download it from ngrok’s site. Alternatively, usenpx localtunnelfor a no-install option. - Start a tunnel to your site. Run
ngrok http 3000(replace 3000 with the port your site runs on). This gives you a public URL likehttps://abc123.ngrok.iothat forwards to your local site. For localtunnel, runnpx localtunnel --port 3000. - Note the public URL. Copy the HTTPS URL from the tunnel output. This is the URL that Percy’s cloud browsers will access.
- Update your test configuration. In your Percy configuration or your test script, change the base URL of your site to the tunnel URL. For example, if you use Cypress, set
baseUrlto the ngrok URL in yourcypress.json. - Run your tests. Execute
percy exec -- npm test. Percy will take screenshots of the tunnel URL, which resolves to your local site behind the firewall. - Keep the tunnel running. Do not close the tunnel until tests finish. Afterward, terminate it with
Ctrl+C.
Common Mistakes
- Forgetting to set PERCY_TOKEN – Without the token, Percy CLI won’t authenticate and builds fail immediately.
- Using the wrong port for the proxy agent – If you change the agent port, you must update the config. Default is 5338.
- Not keeping the tunnel or agent alive – If the process dies mid-test, screenshots will fail with timeouts.
- Using the HTTP tunnel URL instead of HTTPS – Percy requires HTTPS for secure connections; always use the https:// URL from ngrok.
- Hardcoding the tunnel URL in tests – For CI, you need to generate a fresh tunnel URL each run and pass it dynamically, not hardcode a stale one.
Tips
- Use a static tunnel domain – With ngrok, you can reserve a static domain (paid plan) so the URL doesn’t change between runs, simplifying configuration.
- Combine proxy agent with CI – In CI, start the proxy agent as a background service before running tests, and stop it after.
- Test with a dedicated staging environment – If possible, create a staging site that is accessible without VPN but still mirrors production; this avoids the need for tunnels entirely.
- Set a longer timeout – If your site is slow, increase Percy’s screenshot timeout in the config (e.g.,
timeout: 60000) to avoid false failures. - Use environment-specific configs – Store the tunnel URL in an environment variable (like
PERCY_BASE_URL) and reference it in your tests, making it easy to switch between local and tunneled runs.
Troubleshooting
- Build fails with “Connection refused” or “ETIMEDOUT” – This usually means Percy cannot reach your site. Check that the proxy agent is running (for method 1) or that the tunnel is still active (for method 2). Verify the URL is correct and accessible from a public browser.
- Screenshots show a blank page or 404 – The tunnel or proxy is forwarding, but the site may be returning an error for the specific route. Check your site’s logs and ensure the base URL in tests matches the tunnel path.
- Percy CLI says “No snapshots found” – This is often a test runner configuration issue. Ensure your test script is actually calling
percySnapshot()or the equivalent for your framework. - Proxy agent starts but tests still fail – Verify that the agent is listening on the correct port and that your site is accessible from the machine running the agent (try
curl localhost:5338). Also check firewall rules on that machine. - ngrok tunnel shows “ERR_NGROK_6024” – This means the tunnel is blocked by your network’s firewall. Try a different tunnel provider or use the proxy agent method instead.
Frequently Asked Questions
Can I use Percy with a site that requires client-side certificates?
Percy’s proxy agent supports custom CA certificates via the NODE_EXTRA_CA_CERTS environment variable. Set it to your certificate file before starting the agent.
Does the proxy agent work with CI runners on AWS or Azure?
Yes, as long as the runner can reach both your site and Percy’s API. For VPNs, the runner must be inside the VPN; for firewalls, use the tunnel method.
How do I test a site that is only accessible on a localhost port?
Use the tunnel method: start a tunnel to localhost:port and use the public URL in your tests. The proxy agent also works if the site is on localhost, but the tunnel is simpler for one-off runs.
Is there a way to avoid using a tunnel every time?
Yes, if you have a staging environment that is publicly accessible, point Percy to that instead. For local development, you can use a permanent tunnel with a paid plan.
Will Percy work with a site that uses HTTP/2 or WebSockets?
Percy’s screenshot service uses headless Chrome, which supports HTTP/2 and WebSockets. However, ensure your proxy or tunnel supports these protocols; ngrok does, but some older proxies may not.
Can I run multiple sites behind the same proxy agent?
Yes, the proxy agent can forward to multiple destinations if you configure it with a routing rule, but it’s simpler to run separate agents for different sites.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- How to Turn Off Shutter Sound on iPhone
- VPN Setup on iPhone SE: Step-by-Step Guide
- Fix Internet Not Working on Windows 11
- Fix Right Click Not Working in Firefox
- Compare Two Columns with Comma Separated Values in Excel
- How to Limit Ad Tracking on iPhone Apps