How to Use Proxies with Playwright for QA, Scraping, and Geo Testing

Set a Playwright proxy at the browser or browser-context level, not on a single page after launch. Use one sticky route for multi-step QA flows, rotation for independent checks, and verify the exit IP, location, and target behavior before you scale the run.

That one sentence is the whole job done right. The trap most teams fall into is treating the proxy like a per-page setting and then wondering why a checkout test passes locally but uses the wrong region in CI. A Playwright page is not the network boundary. The browser process and the browser context are.

Key takeaways

• Playwright supports HTTP, HTTPS, and SOCKS5 proxy routing at browser launch or per browser context.
• Use a global proxy when the whole test run should share one route; use a context proxy when different projects, regions, or test personas need separate routes.
• Pick the route behavior first: sticky for multi-step journeys (signup, cart, localized pricing), rotation for independent public-page checks.
• Match the proxy product to the job: Residential IPv4 for broad geo-targeting, Residential IPv6 for USA IPv6 routes, Datacenter IPv6 for speed-first IPv6 checks.
• Verify the route three times before you trust a result: the proxy alone, the proxy inside Playwright, then the real target path.

The short answer

Use Playwright's built-in proxy option. Put it at browser launch when every page and context should share one route. Put it at the browser-context level when you need separate routes for separate test groups: different countries, different test personas, or isolated browser sessions inside one process.

The setup is easy. The decision that actually matters is route behavior. A checkout test, a signup flow, or a localized UI test needs a sticky route so the session does not change mid-journey. A price sample, a search-result check, or an independent public-page monitor usually works better with rotation, because each session can start fresh.

The official Playwright network documentation confirms proxy settings can be configured globally for the browser or individually for each browser context (Microsoft, 2024). That browser-level control is exactly why Playwright suits QA, public-data collection, and geo testing better than a plain HTTP client.

Where Playwright proxy settings belong

Playwright gives you three places to set a proxy. The right one depends on how much isolation your workflow needs.

• Test config proxy — every test in a project uses the same route. Simple, but less flexible for mixed-region suites.
• Browser launch proxy — one browser process uses one route. Good for scripts and workers; not enough when you need per-region contexts.
• Browser context proxy — each context gets its own route, region, or session behavior. The most control, but you manage lifecycle and verification yourself.

This distinction is the part people skip. Because the page is not the network boundary, setting the proxy at the wrong scope is how a script passes on your laptop and still leaves through the wrong route in CI.

The Playwright BrowserType API documents the proxy object fields: a server, optional hosts to bypass, and optional username and password (Microsoft, 2024). Keep those values in environment variables or your secret manager. Never commit proxy credentials into test files.

Option 1: configure a proxy in playwright.config.ts

Use this when a whole Playwright project should run from one route. It reads cleanly for a geo-specific project named something like us-desktop, uk-checkout, or eu-localization.

1import { defineConfig } from '@playwright/test';
2
3export default defineConfig({
4  use: {
5    proxy: {
6      server: process.env.PROXY_SERVER,
7      username: process.env.PROXY_USERNAME,
8      password: process.env.PROXY_PASSWORD,
9    },
10  },
11});

A good CI setup makes the route explicit. One project runs a US residential route, another runs a Datacenter IPv6 route. Keep the project name, the env-var names, and the expected region visible in the test report so a failed screenshot is easy to interpret a week later.

Option 2: configure a proxy at browser launch

Use launch-level settings for standalone scripts, workers, or one-off jobs where every page should leave through the same route.

1import { chromium } from 'playwright';
2
3const browser = await chromium.launch({
4  proxy: {
5    server: process.env.PROXY_SERVER,
6    username: process.env.PROXY_USERNAME,
7    password: process.env.PROXY_PASSWORD,
8  },
9});
10
11const page = await browser.newPage();
12await page.goto(process.env.TARGET_URL ?? 'https://example.com/');
13await browser.close();

This pattern is easy to reason about. The browser starts on one network route and every page inherits it. Reach for it when a batch has one location, one proxy product, and one session model.

Option 3: configure a proxy per browser context

Use context-level settings when one browser process needs multiple isolated routes. This is the right tool for regional QA suites, separate test accounts, or comparing how the same public page renders from different locations.

1import { chromium } from 'playwright';
2
3const browser = await chromium.launch();
4
5const usContext = await browser.newContext({
6  proxy: {
7    server: process.env.US_PROXY_SERVER,
8    username: process.env.US_PROXY_USERNAME,
9    password: process.env.US_PROXY_PASSWORD,
10  },
11});
12
13const ukContext = await browser.newContext({
14  proxy: {
15    server: process.env.UK_PROXY_SERVER,
16    username: process.env.UK_PROXY_USERNAME,
17    password: process.env.UK_PROXY_PASSWORD,
18  },
19});
20
21const usPage = await usContext.newPage();
22const ukPage = await ukContext.newPage();
23
24await Promise.all([
25  usPage.goto(process.env.TARGET_URL ?? 'https://example.com/'),
26  ukPage.goto(process.env.TARGET_URL ?? 'https://example.com/'),
27]);
28
29await usContext.close();
30await ukContext.close();
31await browser.close();

Use context isolation for legitimate work: QA, localization checks, public-data testing, and clean workflow separation. Keep logs that show which route, region, and test job produced each result. It is not a shortcut for behavior that breaks a target site's terms.

How to choose the right ColdProxy route

The proxy product should match the test job, not just the code sample. Here is how the four ColdProxy plans map to common Playwright workflows.

• Multi-country localization QA → Residential IPv4. ColdProxy's Residential IPv4 covers 195+ countries with Country, State, City, ZIP, and ASN targeting from a 70M+ global Residential IPv4 pool. Both Residential IPv4 plans share that coverage; they differ only in billing.
• Multi-step browser flows → Residential IPv4 with sticky sessions. Residential IPv4 supports rotating or sticky sessions configurable from 5 seconds up to 24 hours (default 60 seconds), which is enough to hold a route through a checkout or signup journey.
• USA IPv6 browser testing → Residential IPv6. This plan runs USA-only residential IPv6 routes (city cue "USA - Ashburn") with an included /32 IPv6 subnet, Mbps speed tiers, sticky or rotating sessions, HTTP/HTTPS/SOCKS5, and TCP/UDP.
• Speed-first IPv6 checks → Datacenter IPv6. Mbps-tiered Datacenter IPv6 covers a real metro list — US cities plus Toronto, London, Frankfurt, Amsterdam, Paris, Tokyo, Singapore, Sydney, and more — with a private /48 subnet per supported location, ordered together.
• Basic validation before a run → the [ColdProxy Proxy Checker](https://coldproxy.com/tools/proxy-checker/). It confirms reachability, exit IP, and location before you wire a proxy into Playwright.

For a broad browser QA suite, the web and app testing proxy use case is the natural starting page — it is already framed around Selenium, Playwright, and Puppeteer QA across many countries.

Sticky vs rotating sessions in Playwright

The most common Playwright proxy mistake is choosing rotation for a workflow that needs continuity.

Use a sticky route when the browser must hold the same network path through a flow: signup QA, cart tests, regional pricing checks, multi-step forms, and any test where the target hands the browser a session cookie. If the route changes halfway through, the result can look like an app bug when the proxy config actually caused the mismatch.

Use rotation when each browser session is independent: separate public-page checks, sampling search results from a region, checking localized landing pages, or short monitor jobs where continuity is not part of the test.

ColdProxy's plans make this practical. Premium Residential Geo Target IPv4 (Unmetered) leads with Mbps speed tiers and supports rotating or sticky sessions from 5 seconds up to 24 hours. Residential IPv6 and Datacenter IPv6 use the same sticky-or-rotating control, with sticky duration configurable from 5 seconds all the way to FOREVER for long-held sessions.

Verify before you trust the result

A Playwright script can finish without proving the proxy route was correct. Add a verification step before the real target, especially in CI.

1import { test, expect } from '@playwright/test';
2
3test('proxy route reports the expected exit IP and region', async ({ page }) => {
4  // ColdProxy exit-IP echo endpoint (IPv4). Use api6.vipv6proxy.com for IPv6.
5  await page.goto('https://api.vipv6proxy.com/api/checker/my-ip', {
6    waitUntil: 'domcontentloaded',
7  });
8
9  const body = await page.locator('body').innerText();
10  const data = JSON.parse(body); // { ip, version, country, city, ... }
11
12  expect(data.country).toBe(process.env.EXPECTED_COUNTRY ?? '');
13});

That endpoint returns JSON with the exit ip, version, country, and city, so you can assert the browser actually left through the region you expected. For IPv6 routes, point at https://api6.vipv6proxy.com/api/checker/my-ip instead — browsers cannot reliably force both families against one hostname. You can also drop the proxy into the ColdProxy Proxy Checker first, then confirm the same exit inside Playwright. A proxy can be alive and still be the wrong route for the job.

Troubleshooting Playwright proxy failures

Split failures into layers before you touch the script. The symptom usually points at one layer.

• Browser will not launch → proxy syntax or credentials. Check the scheme, host, port, username, password, and how the secret loads.
• Diagnostic page shows the wrong region → route selection. Check the country/city/ASN target, the sticky token, and which context the request used.
• Target works without the proxy but fails with it → target behavior or route fit. Check terms, rate limits, IPv4/IPv6 support, and session continuity.
• First page works, a later step fails → session model. Check sticky duration, cookie flow, context reuse, and any mid-flow route change.
• Everything times out → network path. Check proxy reachability, DNS, target availability, and CI firewall rules.

MDN's proxy and tunneling guide is useful background: a forward proxy sits between the client and destination, and HTTP CONNECT is how HTTPS traffic is tunneled through an HTTP proxy (Mozilla, 2024). That framing is why a browser automation failure can come from the client, the proxy, the target, or the tunnel path — and why classifying the layer first saves time.

A safe Playwright proxy checklist

Run through this before you scale a Playwright proxy job.

1. Confirm the target allows your intended automated access; review its terms, robots.txt where relevant, and applicable data-protection rules.
2. Choose the proxy product by workflow: residential for trust and geo-targeting, datacenter for speed-first IPv6 checks, IPv4 or IPv6 based on what the target supports.
3. Decide the proxy scope: config, browser launch, or browser context.
4. Decide the session model: sticky for continuity, rotating for independent checks.
5. Store proxy credentials in environment variables, not source control.
6. Test the proxy directly before Playwright.
7. Test the route inside Playwright against an exit-IP endpoint.
8. Run one real target path slowly before adding concurrency.
9. Log the route label, expected region, browser project, and session mode with every run.

Google Search Central notes that robots.txt mainly manages crawler access and request load (Google, 2024). Treat that as one input, not the whole compliance review — your team still needs to check site terms and applicable law before collecting data at scale.

Common mistakes to avoid

First, do not assume every request uses the proxy just because the code has a proxy object. Verify the route.

Second, do not mix route changes with session-sensitive tests. If the browser adds a cart item from one route and checks out from another, the target may behave differently.

Third, do not pick IPv6 just because it looks newer. Use IPv6 when the target path supports it and the workflow benefits. If the target or a dependency is IPv4-only, choose the right Residential IPv4 plan instead.

Fourth, do not read a proxy error as proof the browser test is broken. A 407 points at proxy authentication. A 429 points at rate limiting. A timeout can mean DNS, route, proxy, target, or CI firewall. Classify the error before you change the script.

Frequently Asked Questions

Does Playwright support SOCKS5 proxies?

Yes. Playwright's official docs describe HTTP, HTTPS, and SOCKSv5 support (Microsoft, 2024). Use the correct scheme, such as http:// or socks5://, and confirm your chosen route supports the authentication shape the browser needs. ColdProxy plans support HTTP, HTTPS, and SOCKS5 across TCP and UDP.

Should I set the proxy globally or per context?

Set it globally when the entire test run should use one route. Use context-level proxies when different tests need different regions, products, or session models inside the same browser process. The context level is the only place you get true per-region isolation in one running browser.

Which ColdProxy plan fits Playwright geo testing?

For multi-country browser QA, start with Residential IPv4: it covers 195+ countries with sticky or rotating sessions. For USA IPv6 checks, use Residential IPv6. For speed-first IPv6 testing across the supported metro list, use Datacenter IPv6. Compare them on the pricing page.

How do I confirm Playwright is really using the proxy?

Check the proxy outside Playwright first, then load an exit-IP endpoint inside Playwright and assert the IP and region — for example https://api.vipv6proxy.com/api/checker/my-ip for IPv4. After that, run the real target path and compare its behavior against the expected route.

Can I use rotating proxies with Playwright?

Yes, but only when each browser session can be independent. Multi-step flows usually need a sticky route long enough to finish the journey without changing path mid-session. ColdProxy sticky sessions run from 5 seconds up to 24 hours on Residential IPv4, and up to FOREVER on Residential IPv6 and Datacenter IPv6.

What to do next

Start with one route, one target, and one Playwright project. Confirm the proxy works outside the browser, then inside Playwright, then against the real target. Once the result is stable, add regions, contexts, or concurrency in small steps.

For a practical starting point, compare the current plan families on the ColdProxy pricing page and test candidate proxies with the free Proxy Checker before you wire them into a production Playwright job. The shortest billing window — hourly where the plan supports it — is a low-commitment way to validate a route against your real workflow. Free trials may also be available after individual review: tell ColdProxy on Telegram or in a support ticket what you want to test and the capacity you need.