Configure a proxy in Playwright

Choose the scope of the test

Playwright supports a proxy at browser launch or on an individual browser context. Use a context for an isolated scenario. The proxy username and password are separate from httpCredentials, which authenticates to a website.

In a Node.js example project, install playwright and its Chromium browser with npm install playwright followed by npx playwright install chromium. Set PROXY_URL to your actual HTTP(S) gateway; https://proxy.example.invalid:8443 is an illustration. Inject PROXY_USERNAME and PROXY_PASSWORD privately.

Run a bounded navigation

Save as proxy-browser.mjs and run node proxy-browser.mjs. This example uses username/password authentication for an HTTP(S) proxy; do not assume these authentication options also work with a SOCKS gateway.

import { chromium } from 'playwright';

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error('Missing environment variable: ' + name);
  return value;
}

const proxy = {
  server: required('PROXY_URL'),
  username: required('PROXY_USERNAME'),
  password: required('PROXY_PASSWORD'),
};
const browser = await chromium.launch({ timeout: 30_000 });
try {
  const context = await browser.newContext({ proxy });
  context.setDefaultTimeout(15_000);
  context.setDefaultNavigationTimeout(30_000);
  const page = await context.newPage();
  const response = await page.goto('https://example.com/', {
    waitUntil: 'domcontentloaded',
  });
  if (!response || !response.ok()) throw new Error('Navigation did not succeed');
  console.log({ status: response.status() });
  await context.close();
} finally {
  await browser.close();
}

Separate page success from network success

A navigation response describes the main document, not every image, script or API request the page makes. For a real test, assert the exact screen or response your workflow depends on. Use a page you control and keep the assertion tied to one observable outcome.

A single page can generate many requests. If your provider rotates per request, confirm how it handles those connections before expecting one stable exit throughout a browser flow. Cookies remain browser state; choosing a sticky proxy does not create or restore them.

When a page times out, first repeat a small request through the same gateway in curl. Then inspect sanitized browser request failures and the specific failing resource. Avoid collecting screenshots or traces containing real account data during a basic connectivity check.