Configure a proxy at the scope your browser automation framework supports, and verify it using the exact browser and proxy endpoint you will run in production. In Playwright, you can set a proxy for the test run, browser launch, or an individual browser context; the proxy object can specify a server, optional credentials, and hosts to bypass. Browser traffic and downloading the browser binary are separate network paths, so proxying one does not automatically proxy the other.
Choose the proxy scope that matches your sessions
Playwright documents HTTP(S) and SOCKSv5 proxy support. The configuration scope determines which sessions use the endpoint; it does not change the proxy provider’s capabilities or make an incompatible authentication method work.
| Scope | Use it when | Where to configure |
|---|---|---|
| Playwright Test run | The test run should share a proxy configuration. | use.proxy in the Playwright Test configuration |
| Browser instance | All contexts created from that launched browser should use the same proxy. | chromium.launch({ proxy: ... }) |
| Browser context | Different sessions need different proxy routes. | browser.newContext({ proxy: ... }) |
Playwright documents both global and per-context configuration in its network guide and the BrowserType API reference. Prefer context-level configuration when isolating sessions with different routes. Prefer a shared scope when the whole run uses one endpoint.
Configure a proxy in Playwright
Browser launch configuration
Use the endpoint, protocol, bypass hosts, and authentication details supplied by your proxy service. The hostname and port below are examples; replace them with the real values. Store credentials in environment variables rather than committing them to source code.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
import { chromium } from 'playwright';
const browser = await chromium.launch({
proxy: {
server: 'http://proxy.example:3128',
username: process.env.PROXY_USER,
password: process.env.PROXY_PASSWORD,
bypass: '.internal.example,localhost',
},
});
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('https://example.com');
console.log('Page title:', await page.title());
await browser.close();The server identifies the proxy and its protocol. The optional username and password are for proxy authentication; bypass is a comma-separated list of hosts that should connect directly. Match the URL scheme to the endpoint’s supported protocol. A syntactically valid URL is not evidence that the endpoint is reachable or that its authentication method is supported.
Playwright Test configuration
For a test run that shares one proxy, configure use.proxy in playwright.config.js. Read secrets from the environment when tests start:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
proxy: {
server: process.env.PROXY_SERVER,
username: process.env.PROXY_USER,
password: process.env.PROXY_PASSWORD,
bypass: '.internal.example,localhost',
},
},
});Set PROXY_SERVER, PROXY_USER, and PROXY_PASSWORD in the test environment. If your endpoint does not require credentials, omit the username and password fields rather than filling them with empty or sample values. Confirm that the proxy configuration applies to the test projects and browser runs you intend to cover.
Different proxy for a specific browser context
When sessions need distinct routes, pass the proxy when creating each context. The following illustrates two contexts using different endpoint settings:
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
import { chromium } from 'playwright';
const browser = await chromium.launch();
const usContext = await browser.newContext({
proxy: {
server: process.env.PROXY_SERVER_A,
username: process.env.PROXY_USER_A,
password: process.env.PROXY_PASSWORD_A,
},
});
const secondContext = await browser.newContext({
proxy: {
server: process.env.PROXY_SERVER_B,
username: process.env.PROXY_USER_B,
password: process.env.PROXY_PASSWORD_B,
},
});
const firstPage = await usContext.newPage();
const secondPage = await secondContext.newPage();
await Promise.all([
firstPage.goto('https://example.com'),
secondPage.goto('https://example.org'),
]);
await browser.close();Replace the variable names and destinations with values suitable for your test. This pattern gives each context an independent proxy setting; it does not prove that either endpoint exits in a particular location or meets a target site’s access rules.
Set protocol, credentials, and bypass hosts carefully
Protocol and endpoint
The Playwright API documents HTTP and SOCKS proxies, and its network guide describes HTTP(S) and SOCKSv5. Use the exact protocol and endpoint format documented by the provider. If an endpoint uses an unsupported scheme or port, changing browser options will not make it compatible.
Proxy credentials are not website credentials
Proxy credentials authenticate the browser to the proxy. Website credentials authenticate a user to the destination site. They are separate concerns and should not be substituted for one another. If a destination site itself requires sign-in, configure that as part of the site interaction using the site’s supported authentication flow.
Be careful when both the proxy and destination site use HTTP authentication. Browser and framework behavior can depend on the specific authentication challenge and version. Do not assume one credential pair will satisfy both.
Recommended Free Tools
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Bypass list
Use the optional comma-separated bypass value for hosts that should not go through the proxy, such as internal services or localhost in a test environment. Check how the exact hostnames in your test resolve and whether a bypass is intended; an overly broad exception can route traffic differently than expected.
Configure Puppeteer with version-specific care
A third-party Puppeteer proxy guide describes passing a proxy through Chromium launch arguments and using page.authenticate() for HTTP proxy authentication challenges. The example below follows that pattern; adapt the endpoint and credentials to your environment:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
args: ['--proxy-server=http://proxy.example:3128'],
});
const page = await browser.newPage();
await page.authenticate({
username: process.env.PROXY_USER,
password: process.env.PROXY_PASSWORD,
});
await page.goto('https://example.com');
console.log('Page title:', await page.title());
await browser.close();Validate this setup against the Puppeteer and Chrome versions you actually use. The guide notes that Chrome’s SOCKS5 proxy implementation does not support SOCKS5 authentication, and warns that a single authentication pair can conflict if both proxy and destination site demand different credentials. Treat these as framework/browser-specific cautions, not a guarantee about every version or deployment.
Proxy browser installation separately from page traffic
Configuring the browser’s page traffic does not configure how Playwright downloads its browser binaries. If installation runs in an environment that must use a proxy, Playwright documents setting HTTPS_PROXY for the install command:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesRank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
HTTPS_PROXY=http://proxy.example:3128 npx playwright installFor environments where a corporate intercepting proxy causes a certificate-chain error, Playwright’s browser installation documentation recommends supplying the custom root certificate with NODE_EXTRA_CA_CERTS. It also documents PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT for slow browser archive downloads.
NODE_EXTRA_CA_CERTS=/path/to/corporate-root.pem
HTTPS_PROXY=http://proxy.example:3128
PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000
npx playwright installUse the certificate path and timeout value appropriate to your environment; the value above is an example. Do not disable TLS certificate verification to work around a certificate error. Follow your organization’s certificate and proxy policies. See the official Playwright browser installation guidance for the relevant environment variables and setup.
Verify the route in the framework you will run
Test a real browser session rather than relying only on a successful launch. Use a controlled destination or an endpoint you are authorized to query, and check observed egress against the proxy’s expected behavior. The documentation establishes framework configuration options; it does not establish that a specific provider works, is suitable for your use, or guarantees anonymity, reduced blocking, or a particular location.
- Confirm the endpoint. Check the provider’s exact protocol, hostname, port, authentication mode, and any network allowlisting requirements.
- Confirm the scope. Ensure the configuration is applied at test-run, browser, or context scope as intended.
- Check exceptions. Verify bypass hosts and ensure the test destination is not accidentally excluded.
- Run a browser navigation. Navigate to a controlled page and inspect the result, not just the browser process startup.
- Compare observed egress. Use an authorized endpoint or service that reports the request source, then compare it with the expected proxy route.
- Test installation independently. If browser installation is failing, test the documented installation proxy variables separately from page-traffic settings.
Troubleshoot common failures
| Symptom | Likely cause | What to check or change |
|---|---|---|
| Browser launch succeeds, but navigation fails | Proxy host or port is unreachable, scheme is wrong, or the endpoint rejects the connection. | Check endpoint spelling, protocol, port, network access, and provider status from the same environment. |
| Authentication challenge or proxy error | Credentials are missing, incorrect, or not accepted in the configured mode. | Confirm the proxy’s required authentication method and environment variables. Keep proxy login distinct from destination-site login. |
| Some hosts do not use the proxy | A bypass entry matches the destination, or configuration is set at a narrower/different scope than expected. | Review the comma-separated bypass list and the scope applied to the affected context or test. |
| SOCKS5 endpoint fails with authentication | The browser/framework combination may not support that authentication flow. | Check the provider’s protocol requirements and the exact framework/browser version. For Puppeteer with Chrome, consult the version-sensitive SOCKS5 caveat above. |
| Browser installation download fails | Installation traffic is not routed through the proxy, the proxy intercepts TLS, or archive transfer times out. | Use Playwright’s documented HTTPS_PROXY, configure the trusted root through NODE_EXTRA_CA_CERTS when appropriate, or set its download connection timeout. |
| Proxy works for one test but not another | Those tests may use different browser projects, contexts, or configuration. | Inspect the actual run configuration and create explicit context-level settings where sessions need separate routes. |
Performance, reliability, and cost considerations
A proxy adds another network dependency to browser automation. The supplied framework documentation describes configuration, not latency measurements, availability guarantees, or provider quality. Test from the same runtime and network where the suite will execute, and account for proxy connectivity and authentication failures in your test diagnostics.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Choose an endpoint based on the protocol, credentials, bypass needs, geography or policy requirements your workflow actually has. The sources cited here do not compare proxy providers or establish that proxying avoids rate limits or access controls. Follow the destination site’s rules and your organization’s requirements.
Or skip the browser setup
If your task is to capture a website rather than run a general interactive browser workflow, ScreenshotNeo offers a one-request screenshot API. It does not configure a custom proxy for your Playwright or Puppeteer session; it is an alternative when you need an image or PDF capture instead of managing browser routing yourself.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for request details. ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools, and the Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for the free plan.
Frequently Asked Questions
Does proxy configuration guarantee a particular IP location?
No. The cited framework documentation explains how to configure a proxy, not the exit location or performance of a particular endpoint. Verify the endpoint’s behavior with a controlled, authorized check.
Can I use these Playwright settings in Selenium?
No direct equivalence is established here. The configuration examples are for Playwright, and Puppeteer has its own browser-specific approach; consult the documentation for your Selenium binding and browser.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
