How to Use Proxies with Playwright

Configure a global proxy in Playwright Test

For a suite where every page uses the same endpoint, place the proxy under use in playwright.config.ts. Read secrets from the environment so the config can be committed without publishing credentials.

import { defineConfig } from '@playwright/test';

export default defineConfig({
  workers: 2,
  use: {
    proxy: {
      server: process.env.PROXY_SERVER!,
      username: process.env.PROXY_USERNAME,
      password: process.env.PROXY_PASSWORD,
      bypass: 'localhost,127.0.0.1'
    },
    trace: 'retain-on-failure'
  }
});

Start the test process with the values supplied by your local secret store or CI platform. A typical server value is http://proxy.example:8080 or socks5://proxy.example:1080. Do not paste a production password into the repository, test name, screenshot filename or console output.

Use bypass only for hosts that must connect directly, such as a local application under test. Review this list carefully: a broad suffix can send more traffic outside the proxy than intended.

Verify the exit inside the test

import { test, expect } from '@playwright/test';

test('uses the expected proxy country', async ({ page }) => {
  await page.goto('https://api.ipify.org?format=json');
  const result = JSON.parse(await page.textContent('body') || '{}');

  expect(result.ip).toMatch(/^d{1,3}(.d{1,3}){3}$/);
});

An IP format assertion proves only that an address was returned. For production QA, compare it with the expected assigned exit and use the IP location checker or a controlled service that returns the evidence your test needs.

Use a different proxy for each browser context

Playwright browser contexts are isolated, incognito-like sessions. The official test isolation guide explains that cookies, local storage and session storage are separated between contexts. Proxy assignment should follow the same boundary: one context, one stable endpoint, one documented test scenario.

import { chromium } from 'playwright';

const browser = await chromium.launch();

const context = await browser.newContext({
  proxy: {
    server: process.env.PROXY_SERVER!,
    username: process.env.PROXY_USERNAME,
    password: process.env.PROXY_PASSWORD
  },
  locale: 'en-GB',
  timezoneId: 'Europe/London'
});

const page = await context.newPage();
await page.goto('https://example.com');

await context.close();
await browser.close();

Location-sensitive QA often controls locale and time zone as well as network exit. Keep those values explicit, but do not claim the proxy changes every browser signal. The website localization testing guide explains how cookies, account state, language and delivery settings can alter the page independently.

Playwright proxy example in Python

The same configuration is available in the Python binding. The synchronous example below launches Chromium through an authenticated proxy, verifies the public IP response and closes the browser in a finally block.

import json
import os
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(
        proxy={
            "server": os.environ["PROXY_SERVER"],
            "username": os.getenv("PROXY_USERNAME"),
            "password": os.getenv("PROXY_PASSWORD"),
        }
    )
    try:
        page = browser.new_page()
        page.goto("https://api.ipify.org?format=json")
        result = json.loads(page.text_content("body") or "{}")
        print("Proxy exit:", result.get("ip"))
    finally:
        browser.close()

Mask the printed address if test reports are public. Never print the proxy URL when it contains embedded credentials. If you already use Python for HTTP requests, link this browser test to the broader Python proxy guide rather than maintaining unrelated credential formats.

Install Playwright browsers behind a proxy

Downloading the browser binaries is a separate network operation from page traffic. Playwright documents HTTPS_PROXY for browser downloads, NODE_EXTRA_CA_CERTS for an authorized internal certificate authority, and a download connection timeout for slow networks in its browser installation guide.

# PowerShell
$Env:HTTPS_PROXY = "http://proxy.example:8080"
npx playwright install

# Linux or macOS
HTTPS_PROXY="http://proxy.example:8080" npx playwright install

This installation proxy does not automatically configure later test pages. Set page traffic through the Playwright proxy option as shown above. Do not disable TLS verification to silence a certificate problem; install the approved CA correctly or ask the network owner to fix the trust chain.

Parallel workers, sessions and proxy rotation

Do not pick a random proxy for every navigation. A login or multi-page journey normally needs one stable exit for the life of its context. Assign a proxy at worker or test boundary, record the masked proxy ID, and release it only after the context closes.

• Limit workers to the tested concurrent capacity of the proxy plan.
• Use one proxy for a complete stateful test journey.
• Allocate different accounts to tests that modify server-side state.
• Quarantine an endpoint after repeated transport or location failures.
• Keep retries bounded and preserve the original failure evidence.
• Close pages, contexts and browsers even when an assertion fails.

The static versus rotating proxy guide helps choose between stable sessions and independent jobs. For capacity planning, use How Many Proxies Do You Need? rather than equating worker count with a safe request rate.

Debug common Playwright proxy failures

Enable a Playwright trace for failures and listen to request and response events when the application path is unclear. Do not log authorization headers or proxy passwords. The proxy error code guide provides a layer-by-layer path for 407, 403, 429, 502 and timeouts.

Production-ready Playwright proxy checklist

• Use a supported Playwright version and official proxy options.
• Load proxy credentials from environment or a secret manager.
• Verify the public exit before the main test.
• Keep one stable proxy per stateful browser context.
• Record locale, time zone, device and account state beside the exit.
• Bound worker concurrency, timeouts and retries.
• Retain traces on failure with sensitive values redacted.
• Close every context and browser in cleanup code.

For framework comparisons, see the Selenium proxy guide and Puppeteer proxy guide. Playwright is often the most direct choice when per-context proxy settings and cross-browser projects are central to the test design.