# Configure a proxy in Playwright

Source: https://ipvolt.com/guides/playwright-proxy-setup
Markdown: https://ipvolt.com/guides/playwright-proxy-setup.md

[Home](https://ipvolt.com/index.md) / [Guides](https://ipvolt.com/guides.md) / [Configure a proxy in Playwright](https://ipvolt.com/guides/playwright-proxy-setup.md)

Category: Integration
Reviewed: 2026-09-10
Reading time: 4 minutes
Author: ipvolt

Set an authenticated HTTP proxy for a Playwright browser context, keep test state isolated, and diagnose navigation separately from subresources.

## The starting point

Route a controlled browser test through a proxy while keeping credentials, browser state and navigation failures easy to reason about.

## 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.

### proxy-browser.mjs · Playwright Chromium

```javascript
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.


## Before you ship

- Use a fresh context for the scenario.
- Keep proxy and website credentials separate.
- Verify the application's real success condition after navigation.

## Sources & further reading

- [Playwright: HTTP proxy and network events](https://playwright.dev/docs/network#http-proxy)
- [Playwright: browser contexts and timeouts](https://playwright.dev/docs/api/class-browsercontext)
- [Playwright: navigation response behavior](https://playwright.dev/docs/api/class-page#page-goto)

## Related guides

- [Rotating vs sticky proxies: plan for session continuity](https://ipvolt.com/guides/rotating-vs-sticky-proxies.md)
- [Use a proxy with curl](https://ipvolt.com/guides/curl-proxy-setup.md)
- [Mobile vs residential proxies: build a useful evaluation](https://ipvolt.com/guides/mobile-vs-residential-proxies.md)

## About ipvolt

Examples use generic proxy settings, with links to the original technical documentation. Product-specific behavior must be checked with your provider. ipvolt is still in development.

## Know when access opens.

ipvolt · In development

We’re building proxy infrastructure for developers and data teams. Join the interest list for a heads-up when ipvolt is ready.

Consent: One email when access opens. Nothing else.

[Get early access](https://ipvolt.com/guides/playwright-proxy-setup#waitlist-closing). Use the email form on this page to join the interest list.

[Privacy](https://ipvolt.com/privacy)