Playwright Proxy Setup

Use this guide to connect InstantProxies to Playwright and validate that the browser is actually sending traffic through the proxy.

For most users, the right goal is simple: launch the browser with the proxy, confirm the connection works, then move into your real automation flow. Do not start with a large workflow before the baseline browser path is proven.

Use this page when

Use this page when:

you want to use InstantProxies in Playwright
your workflow depends on a real browser instead of raw HTTP requests
you need to test pages that rely on client-side rendering or browser state
you want to confirm that Playwright is using the proxy before building a larger automation flow

If your workload is mostly request-based, use a language integration guide instead of browser automation.

Before you start

Have these details ready:

proxy host
proxy port
authentication method
a simple test URL

The two common access methods are:

username and password authentication
source IP authorization

If you are using IP authorization, make sure the public IP of the runtime environment is already authorized.

Basic Playwright proxy setup

In Playwright, proxy configuration is usually set at browser launch.

import { chromium } from 'playwright';

const browser = await chromium.launch({
  headless: true,
  proxy: {
    server: 'http://YOUR_PROXY_HOST:PORT'
  }
});

const page = await browser.newPage();
await page.goto('https://httpbin.org/ip', { waitUntil: 'networkidle' });
console.log(await page.textContent('body'));

await browser.close();

Use this first to confirm:

the browser launches successfully
Playwright can reach the proxy
the proxy is actually being used for browser traffic
one simple navigation completes cleanly

Playwright setup with username and password

If your proxy uses credentials, include them in the Playwright proxy configuration.

import { chromium } from 'playwright';

const browser = await chromium.launch({
  headless: true,
  proxy: {
    server: `http://${process.env.INSTANTPROXIES_HOST}:${process.env.INSTANTPROXIES_PORT}`,
    username: process.env.INSTANTPROXIES_USERNAME,
    password: process.env.INSTANTPROXIES_PASSWORD
  }
});

const page = await browser.newPage();
await page.goto('https://httpbin.org/ip', { waitUntil: 'networkidle' });
console.log(await page.textContent('body'));

await browser.close();

Do not hardcode credentials into source files.

Use environment variables or your normal secret-handling path instead.

Playwright setup with IP authorization

If your account is configured to allow traffic from an approved public IP, you can usually omit username and password.

import { chromium } from 'playwright';

const browser = await chromium.launch({
  headless: true,
  proxy: {
    server: 'http://YOUR_PROXY_HOST:PORT'
  }
});

const page = await browser.newPage();
await page.goto('https://httpbin.org/ip', { waitUntil: 'networkidle' });
console.log(await page.textContent('body'));

await browser.close();

This works only when the real runtime environment is already authorized.

A local machine, server, container, and CI runner may all use different public IPs.

Validate the proxy before building the workflow

Before adding logins, multi-page flows, or scraping logic, validate in this order:

browser launch
one simple page load
returned IP or baseline response
repeated execution of the same path
only then add real browser actions

This keeps setup issues separate from workflow issues.

If you have not yet validated the proxy outside Playwright, start with First Request with cURL and Authentication and Access.

Keep proxy setup separate from page logic

Do not rebuild proxy configuration inside page actions or test steps.

Keep these separate:

browser launch settings
proxy settings
authentication values
timeout and wait behavior
page interactions
workflow logic

This makes Playwright easier to debug and easier to reuse.

Use contexts intentionally

Contexts affect:

state isolation
session continuity
cookie reuse
repeated-run behavior
debugging of larger workflows

Create a new context when you need isolation. Reuse a context only when the workflow depends on preserved state.

Weak context rules often make Playwright runs look unstable when the real issue is state reuse.

Make waits and timeouts explicit

Playwright workflows depend on more than just browser launch.

You should think about timing at these boundaries:

launch
page creation
navigation
selector readiness
repeated workflow steps

A page finishing navigation does not always mean the next step is ready.

If timing is the main issue, continue to Timeouts, Retries, and Backoff.

Test repeated runs

One successful browser run is not enough.

Repeat the same simple path several times and check:

whether launch stays consistent
whether navigation timing drifts
whether contexts behave as expected
whether the same runtime still works after repeated execution

Repeated-run stability is a much better signal than first-run success.

Common Playwright proxy mistakes

Typical issues include:

validating only one successful page load
using the wrong runtime IP for allowlisting
mixing proxy configuration into page logic
hardcoding credentials
assuming headless and headed runs behave the same way without checking
starting with a large workflow before the proxy path is validated
treating a browser workflow failure as if it were only a simple request failure

Basic troubleshooting checks

If the Playwright run fails, check these first:

host and port are correct
username and password are correct if used
the real runtime IP is authorized if using IP allowlisting
the same proxy works with cURL from the same environment
the page failure happens at launch, navigation, or later in the workflow

If the problem is still unclear, continue to Authentication and Allowlist Errors or Connectivity Troubleshooting.

Recommended setup sequence

Use this sequence:

confirm the access method
configure the proxy at browser launch
validate one simple page load
repeat the same path from the same environment
make waits and timeouts explicit
only then expand into a larger Playwright workflow

Key points

configure the proxy at browser launch
match the authentication method to the real runtime environment
validate the proxy path before building the full workflow
keep proxy setup separate from page logic
use contexts deliberately
repeated runs matter more than one successful page load

Next step

If you need another browser framework, continue to Puppeteer Proxy Setup or Selenium Proxy Setup.

If Playwright launches correctly but your browser flow still fails, continue to Browser Automation Troubleshooting.