How to Use a Proxy with Playwright

Copy the proxy address and login

Start with the protocol, hostname and port from your proxy provider. For IPMusk Rotating Residential, the HTTP server value is http://gate.ipmusk.com:31212. If you use a Static ISP or Datacenter proxy, use the host and port assigned to that IP. Copy the full generated username if it includes location or session settings.

Keep the proxy server and login in separate fields. An HTTP proxy can carry requests to an HTTPS destination. The scheme in server tells Chromium how to connect to the proxy, while the URL in page.goto() tells it which site to open.

Both examples read the proxy login from environment variables. Set PROXY_USERNAME and PROXY_PASSWORD in the environment that starts the script. For a CI job, supply them through the job's secret settings. The first test needs only a small HTTPS page. Use the example URL for the first navigation. For the route check, choose a small page you control that can report the address of the connection it receives.

Python: set the proxy for a Chromium launch

Install the playwright package with python -m pip install playwright, then run python -m playwright install chromium in the same environment. Save the snippet as check_proxy.py and run it with python check_proxy.py. This example applies the proxy at launch and then opens one page.

The call waits for DOMContentLoaded, when the browser has parsed the HTML and can read the title. The navigation gets 20 seconds. If Chromium cannot make the connection, page.goto() can raise an error before there is an HTTP status to print.

import os
from playwright.sync_api import sync_playwright

with sync_playwright() as playwright:
    browser = playwright.chromium.launch(proxy={
        "server": "http://gate.ipmusk.com:31212",
        "username": os.environ["PROXY_USERNAME"],
        "password": os.environ["PROXY_PASSWORD"],
    })
    try:
        page = browser.new_page()
        response = page.goto(
            "https://example.com/",
            wait_until="domcontentloaded",
            timeout=20_000,
        )
        if response is None:
            raise RuntimeError("No navigation response")
        print(response.status, page.title())
    finally:
        browser.close()

Node.js: set the proxy for one context

In your project, run npm install playwright and npx playwright install chromium. Save this snippet as check-proxy.mjs and run node check-proxy.mjs. It opens a browser without a launch-wide proxy, then supplies the proxy when creating the context that owns the test page.

Pages inside a context share its cookies and storage. A second context starts with a separate session and uses its own proxy settings. In an existing suite, find the code that creates your test page and confirm it uses the intended context.

import { chromium } from "playwright";

const { PROXY_USERNAME, PROXY_PASSWORD } = process.env;
if (!PROXY_USERNAME || !PROXY_PASSWORD) {
  throw new Error("Set PROXY_USERNAME and PROXY_PASSWORD");
}

const browser = await chromium.launch();
try {
  const context = await browser.newContext({
    proxy: {
      server: "http://gate.ipmusk.com:31212",
      username: PROXY_USERNAME,
      password: PROXY_PASSWORD,
    },
  });
  const page = await context.newPage();
  const response = await page.goto("https://example.com/", {
    waitUntil: "domcontentloaded",
    timeout: 20_000,
  });
  if (!response) throw new Error("No navigation response");
  console.log(response.status(), await page.title());
  await context.close();
} finally {
  await browser.close();
}

Either language can use launch-level or context-level settings. Choose the scope that matches your test.

Choose where the proxy applies

Suppose a storefront test checks whether a country-specific shipping banner appears. Give the regional check its own proxied context. Open the same test URL in a fresh context for the baseline and keep the other inputs, such as the browser locale and the test account's shipping address, consistent. That gives you a cleaner comparison when several settings can affect the banner.

Verify the route from the page you opened

Read both the status and title. A response may be a sign-in page or an error page, so confirm it is the page your test expected. To see which address the destination observed, open an IP-check page in that same Playwright context or read the connection address recorded by a test endpoint you operate. If you use an endpoint behind a load balancer, use the client address recorded by the trusted ingress.

If you need a baseline, run the same check in a separate browser session with no proxy setting, on the same runner. Compare what the endpoint sees for the two requests. For a localization test, check the country or available region reported by the service as well. Geolocation services can disagree, so verify with the service that matters to your test.

The script prints the status of the main navigation. A page can return 200 while an API request for the shipping estimate fails. If your test depends on one of those requests, inspect its response in the same context before treating the workflow as ready.

Find the first point of failure

• Browser fails to start. If the error says the browser executable is missing, run the Playwright Chromium install command in the environment that runs the test. This step matters when the local machine and CI use different package versions.
• The proxy reports 407 or the browser reports a proxy authentication error. Recheck the username and password supplied to the process. Playwright's httpCredentials in Node.js, or http_credentials in Python, serve the destination site's HTTP login. Supply proxy credentials in the proxy object.
• The navigation times out or Chromium reports a connection error. Verify the proxy protocol, host and port, and check reachability from the same runner. Use the curl guide below to test the same proxy and destination independently.
• The destination sees a direct address. Check that the page came from the expected context and whether the proxy bypass list includes the hostname. Chromium can also connect to loopback addresses directly. Use a reachable HTTPS test endpoint for your route check.
• The page returns 403 after the route is confirmed. Check whether your test account can open that resource and review the destination logs or access rules if you manage the service.

The snippets use HTTP proxy authentication. Chromium's SOCKS5 routing requires a proxy that accepts unauthenticated connections. Use your provider's HTTP endpoint for the username and password setup shown here.