Playwright Proxy Configuration Guide: Authentication, Isolation and Debugging

A Playwright proxy setup is reliable only when network identity, browser state, timeouts and diagnostics are designed together. This guide shows a production-oriented pattern for authorized localization checks, ad verification, regional QA and public-web testing. It avoids fragile one-off scripts and keeps every failure explainable.

Choose the proxy scope before writing the test

Playwright supports a proxy when launching a browser and when creating a BrowserContext. A launch-level proxy is appropriate when every context in that browser process should share one gateway. A context-level proxy is better when a test matrix needs separate regions, credentials or session policies. Do not rotate an identity in the middle of a workflow that depends on cookies, locale or a stable cart.

A useful rule is one logical identity per context. A context isolates cookies, cache and storage, so it is the natural boundary for a proxy session. Create it, complete the intended scenario, record the result and close it. Reusing one context for unrelated identities makes authentication and debugging much harder.

Keep credentials out of source code

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
  }
});

const page = await context.newPage();
await page.goto(process.env.TARGET_URL, {
  waitUntil: 'domcontentloaded',
  timeout: 30000
});

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

Pass the endpoint and credentials through a secret manager or protected environment variables. Never print the full username, password or session token. In logs, keep only a provider-independent profile name, region, product type and a short irreversible session hash.

Build an isolated regional test matrix

Define the matrix as data rather than duplicating tests. Each row should state the region, proxy product, expected locale, session policy and concurrency limit. For North America, Europe and APAC, run the same authorized destination and the same assertion set. This separates geographic behavior from changes in the test itself.

const profiles = [
  { name: 'region_a', server: process.env.PROXY_REGION_A },
  { name: 'region_b', server: process.env.PROXY_REGION_B },
  { name: 'region_c', server: process.env.PROXY_REGION_C }
];

for (const profile of profiles) {
  const context = await browser.newContext({
    proxy: {
      server: profile.server,
      username: process.env.PROXY_USERNAME,
      password: process.env.PROXY_PASSWORD
    }
  });
  // Run one authorized scenario and capture structured results.
  await context.close();
}

Use layered timeouts

A single large timeout hides the stage that failed. Keep separate budgets for connection and navigation, individual actions, and assertions. A practical starting point is 30 seconds for navigation, 10 seconds for actions and 5 seconds for assertions, then adjust from measured p95 latency. A slower regional route may justify a larger navigation budget, but it should not make a missing element wait indefinitely.

Prefer domcontentloaded plus business-specific assertions to waiting for every network request to stop. Modern pages often keep analytics, chat or streaming connections open. The correct completion signal is the one that proves the authorized workflow is usable.

Retry only transient stages

Test-level retries start a fresh worker, which is valuable because they rebuild browser and application state. Use them sparingly for genuinely intermittent infrastructure failures. For a single navigation, permit a small bounded retry only for transient connection errors or selected server responses. Add exponential backoff and jitter, keep the same session when the workflow requires continuity, and record every attempt.

Do not retry authentication failures, deterministic assertions or policy blocks until the cause is understood. Unlimited retries turn a clear failure into load on the destination and can violate rate limits.

Troubleshooting map

• 407 proxy authentication required: verify endpoint format, credential scope, account status and whether the selected product accepts username/password authentication.
• DNS or connection timeout: compare direct and proxied resolution, verify the gateway host and port, then test a single region with minimal concurrency.
• TLS error: check system time, certificate inspection policy and whether the target hostname is correct. Do not disable certificate validation as a routine fix.
• 429 response: reduce concurrency, honor retry guidance and review the destination's permitted rate.
• 403 or challenge page: confirm authorization, terms and expected browser behavior. Do not treat access controls as a technical obstacle to circumvent.
• Correct page but wrong locale: compare IP region, browser locale, timezone, language headers, cookies and account preferences.

Capture evidence that explains failures

For every run, store the test name, timestamp, region, proxy product, context ID, navigation timing, final status, retry count and assertion result. On failure, capture a screenshot and Playwright trace with secrets removed. A trace can reveal whether the delay occurred before navigation, during a redirect, while loading an API dependency or at an assertion.

Track usable-result rate and p50/p95 latency, not just successful HTTP responses. A page that returns successfully but shows the wrong locale, incomplete content or an invalid session is not a usable result.

Production checklist

• Use one BrowserContext per logical identity and close it after the scenario.
• Store proxy credentials in protected runtime secrets.
• Set navigation, action and assertion timeouts separately.
• Cap concurrency by region and destination.
• Retry only classified transient failures with bounded backoff.
• Redact credentials from traces, screenshots and logs.
• Validate locale, session continuity and business completion.
• Run only against destinations and data you are authorized to test.

Select the right 98IP session model

Regional matrices that benefit from changing network identities can evaluate 98IP rotating residential proxies. Workflows that need a longer-lived identity can compare 98IP static residential proxies. Start with low concurrency, measure usable outcomes and increase volume only after the test is stable.

98IP provides the proxy services described above, and this guide is published by the 98IP team. Use proxy infrastructure lawfully, respect destination terms and rate limits, and never use testing automation to bypass access controls.

Research note

Technical behavior was checked against the Playwright Network, BrowserContext, Timeouts and Retries documentation, consulted 16 August 2026. Source names and the consultation date are shown as plain text under 98IP's zero-external-link policy.