Playwright Proxy Setup

Playwright is Microsoft's open-source browser automation library for end-to-end testing, web scraping, and UI automation. It supports Chromium, Firefox, and WebKit engines with a single API, making it one of the most versatile tools for browser-based data collection and testing. Playwright natively supports proxy configuration at the browser level, which makes integrating Hex Proxies straightforward.

Why Use Proxies with Playwright?

Browser automation scripts that run without proxies use your machine's IP address for every request. Protected websites quickly detect and block repeated requests from the same IP. Residential proxies assign a different IP per session or per request, making your automated browser traffic indistinguishable from regular user visits. This is essential for scraping protected sites, testing geo-restricted content, and running multi-account workflows.

Proxy Configuration with Username/Password Auth

const browser = await chromium.launch({ proxy: { server: 'http://gate.hexproxies.com:8080', username: 'your-hex-username', password: 'your-hex-password', }, });

const page = await browser.newPage(); await page.goto('https://httpbin.org/ip'); console.log(await page.textContent('body')); await browser.close(); ```

Using IP Whitelist Authentication

If you prefer IP whitelisting (no credentials in code), whitelist your server's IP in the Hex Proxies dashboard, then configure the proxy without credentials:

const browser = await chromium.launch({
  proxy: {
    server: 'http://gate.hexproxies.com:8080',
  },
});

Recommended Configuration

• Use **sticky sessions** for login or multi-step flows where you need the same IP across multiple page navigations.
• Use **rotation** for large-scale crawling or parallel test runs where each page visit should appear as a different user.
• Set geo-targeting parameters in your proxy username to route traffic through specific countries or cities.
• Keep concurrency aligned with your plan limits to avoid overwhelming target sites.

Geo-Targeting Example

To route through a specific country, append the country code to your username:

proxy: {
  server: 'http://gate.hexproxies.com:8080',
  username: 'your-hex-username-country-us',
  password: 'your-hex-password',
}

Troubleshooting

• **Blocks or CAPTCHAs**: Reduce concurrency, use longer sticky sessions, and pair proxy rotation with realistic user-agent strings and viewport sizes.
• **Region-locked content**: Set the geo parameter in your proxy config to route through the target country.
• **Timeouts**: Increase Playwright's navigation timeout for residential proxies, which have higher latency than direct connections. Use `page.goto(url, { timeout: 60000 })`.
• **SSL errors**: Ensure you are connecting to the proxy over HTTP (not HTTPS) — the proxy handles the HTTPS connection to the target site.
• **Authentication failures**: Verify your credentials in the Hex Proxies dashboard and ensure your IP is whitelisted if using IP auth.