Configuração de Proxy no Playwright para Testes Headless e Web Scraping: Guia Completo

Playwright é uma das ferramentas mais poderosas para automação de navegador, testes headless e scraping de dados. Mas sem um proxy configurado corretamente, seu script rapidamente será banido por IP: os sites aprenderam a reconhecer solicitações automatizadas e bloqueá-las. Neste guia, vamos explorar todas as maneiras de conectar um proxy no Playwright — desde a configuração básica até a rotação de IP e contorno do Cloudflare.

Por que usar proxy no Playwright e quando é indispensável

O Playwright executa um navegador real (Chromium, Firefox ou WebKit) em segundo plano — isso é o headless. Do ponto de vista do site, você parece um usuário comum, mas apenas até certo ponto. Assim que um único IP começa a fazer centenas de solicitações por hora, os algoritmos de proteção reagem instantaneamente: CAPTCHA, bloqueio temporário, banimento total.

Aqui estão cenários específicos em que o uso de proxy é obrigatório:

• Scraping de marketplaces — Wildberries, Ozon, Avito, Yandex.Market bloqueiam scripts após 50–100 solicitações de um único IP.
• Monitoramento de preços de concorrentes — se você executar verificações a cada 15 minutos, sem troca de IP, você será banido em poucas horas.
• Teste de geolocalização — é necessário verificar como o site aparece para usuários da Alemanha, EUA ou Cazaquistão.
• Preenchimento de formulários e registro de contas — plataformas vinculam contas ao IP e bloqueiam registros em massa.
• Monitoramento de SEO — coleta de posições do Google e Yandex requer troca constante de IP, caso contrário, o mecanismo de busca mostrará CAPTCHA.
• Teste de funções A/B — algumas funcionalidades estão disponíveis apenas para usuários de determinados países ou regiões.

É importante entender: o Playwright por si só não o torna anônimo. Sem proxy, todas as solicitações são feitas a partir do seu IP real. A adição de um proxy é o primeiro e mais importante passo para o funcionamento estável de qualquer script automatizado.

Qual tipo de proxy escolher para automação headless

Nem todos os proxies são igualmente adequados para o Playwright. A escolha depende da tarefa: o que você está scraping, quão agressiva é a proteção do site e qual volume de solicitações você planeja.

Para a maioria das tarefas de scraping, a escolha ideal são proxies residenciais com rotação. Eles possuem IPs reais de usuários domésticos, portanto, os sites não os identificam como data center e não bloqueiam automaticamente. Para sites com proteção agressiva (Cloudflare Bot Management, Akamai), é melhor usar proxies móveis — seus IPs pertencem a operadoras de telefonia, o que gera máxima confiança.

O Playwright suporta os protocolos http, https e socks5. Importante: o SOCKS5 não suporta autenticação via username:password diretamente em algumas versões — mais detalhes na seção sobre erros.

Configuração básica de proxy no Playwright (JavaScript e Python)

O Playwright permite definir um proxy ao iniciar o navegador através do parâmetro proxy. Este é o método mais simples — todas as solicitações do navegador passarão pelo proxy especificado.

JavaScript / Node.js

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({
    proxy: {
      server: 'http://proxy.example.com:8080'
    }
  });

  const page = await browser.newPage();
  await page.goto('https://httpbin.org/ip');
  
  const content = await page.textContent('body');
  console.log(content); // mostrará o IP do proxy

  await browser.close();
})();

Python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(
        proxy={
            "server": "http://proxy.example.com:8080"
        }
    )
    
    page = browser.new_page()
    page.goto("https://httpbin.org/ip")
    
    print(page.text_content("body"))  # mostrará o IP do proxy
    
    browser.close()

Para SOCKS5, basta alterar o esquema no endereço do servidor:

# Python — proxy SOCKS5
browser = p.chromium.launch(
    proxy={
        "server": "socks5://proxy.example.com:1080"
    }
)

Para verificar rapidamente se o proxy está funcionando, abra https://httpbin.org/ip ou https://api.ipify.org — a resposta deve mostrar o IP do proxy, e não o seu real.

Proxy com autenticação por login e senha

A maioria dos provedores de proxy comerciais utiliza autenticação por login e senha — esta é uma prática padrão. O Playwright suporta isso através dos campos username e password no objeto proxy.

JavaScript

const browser = await chromium.launch({
  proxy: {
    server: 'http://gate.proxyprovider.com:7777',
    username: 'your_login',
    password: 'your_password'
  }
});

Python

browser = p.chromium.launch(
    proxy={
        "server": "http://gate.proxyprovider.com:7777",
        "username": "your_login",
        "password": "your_password"
    }
)

Você também pode passar o login e a senha diretamente na URL do servidor proxy — isso é conveniente se você estiver formando a string dinamicamente:

# Autenticação na URL (Python)
proxy_url = f"http://{login}:{password}@gate.proxyprovider.com:7777"

browser = p.chromium.launch(
    proxy={"server": proxy_url}
)

Armazenamento seguro via .env (Python)

import os
from dotenv import load_dotenv
from playwright.sync_api import sync_playwright

load_dotenv()

PROXY_SERVER   = os.getenv("PROXY_SERVER")
PROXY_LOGIN    = os.getenv("PROXY_LOGIN")
PROXY_PASSWORD = os.getenv("PROXY_PASSWORD")

with sync_playwright() as p:
    browser = p.chromium.launch(
        proxy={
            "server":   PROXY_SERVER,
            "username": PROXY_LOGIN,
            "password": PROXY_PASSWORD
        }
    )
    # ...

Rotação de proxy: troca de IP para cada solicitação

Um único proxy não salvará você de um banimento com um grande volume de solicitações. Para scraping sério, é necessária a rotação de IP — troca automática do servidor proxy em intervalos determinados ou para cada nova solicitação.

Existem duas abordagens para rotação no Playwright:

Abordagem 1: Endpoint de proxy rotativo

A maioria dos provedores de proxies residenciais fornece um único endereço de gateway, que muda automaticamente o IP a cada conexão. Você não precisa escrever a lógica de rotação — ela está embutida do lado do provedor.

# Um endpoint — novo IP a cada conexão do navegador
browser = p.chromium.launch(
    proxy={
        "server":   "http://rotating.proxyprovider.com:8888",
        "username": "your_login",
        "password": "your_password"
    }
)

Abordagem 2: Rotação manual através de lista de proxies

Se você tiver uma lista de proxies estáticos, pode implementar a rotação manualmente — criando um novo navegador ou contexto para cada iteração:

import random
from playwright.sync_api import sync_playwright

PROXY_LIST = [
    {"server": "http://proxy1.example.com:8080", "username": "user", "password": "pass"},
    {"server": "http://proxy2.example.com:8080", "username": "user", "password": "pass"},
    {"server": "http://proxy3.example.com:8080", "username": "user", "password": "pass"},
]

URLS_TO_SCRAPE = [
    "https://example.com/page1",
    "https://example.com/page2",
    "https://example.com/page3",
]

with sync_playwright() as p:
    for url in URLS_TO_SCRAPE:
        proxy = random.choice(PROXY_LIST)  # proxy aleatório
        
        browser = p.chromium.launch(proxy=proxy)
        page = browser.new_page()
        
        page.goto(url)
        # ... scraping de dados ...
        
        browser.close()  # fecha o navegador, muda o IP

Abordagem 3: Rotação através de BrowserContext (sem reiniciar o navegador)

with sync_playwright() as p:
    browser = p.chromium.launch()  # navegador sem proxy
    
    for i, url in enumerate(URLS_TO_SCRAPE):
        proxy = PROXY_LIST[i % len(PROXY_LIST)]  # em loop
        
        # Novo contexto com novo proxy — mais rápido do que reiniciar o navegador
        context = browser.new_context(proxy=proxy)
        page = context.new_page()
        
        page.goto(url)
        # ... scraping ...
        
        context.close()  # fecha o contexto, não o navegador
    
    browser.close()

A terceira abordagem é a mais eficiente para scraping em massa. Reiniciar o navegador leva de 2 a 4 segundos, enquanto criar um novo contexto leva menos de 100 milissegundos.

Proxy em nível de contexto e página

O Playwright suporta uma arquitetura flexível: um navegador pode ter vários contextos isolados, cada um com seu próprio proxy. Isso permite que você trabalhe paralelamente com vários IPs dentro de um único processo.

Vários contextos com diferentes proxies (scraping paralelo)

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();

  // Contexto 1 — proxy da Alemanha
  const context_de = await browser.newContext({
    proxy: {
      server: 'http://de-proxy.example.com:8080',
      username: 'user',
      password: 'pass'
    }
  });

  // Contexto 2 — proxy dos EUA
  const context_us = await browser.newContext({
    proxy: {
      server: 'http://us-proxy.example.com:8080',
      username: 'user',
      password: 'pass'
    }
  });

  const page_de = await context_de.newPage();
  const page_us = await context_us.newPage();

  // Execução paralela
  await Promise.all([
    page_de.goto('https://example.com'),
    page_us.goto('https://example.com')
  ]);

  // Ambas as páginas veem IPs diferentes
  console.log('DE IP:', await page_de.textContent('body'));
  console.log('US IP:', await page_us.textContent('body'));

  await browser.close();
})();

Esta abordagem é ideal para testar geolocalização: você verifica simultaneamente como o site é exibido para usuários de diferentes países, sem precisar iniciar várias instâncias do navegador.

Contornando proteção contra bots: Cloudflare, Akamai, DataDome

Proxy é apenas parte da solução. Sistemas modernos de proteção contra bots analisam dezenas de sinais simultaneamente: fingerprint do navegador, comportamento do mouse, velocidade de preenchimento de formulários, cabeçalhos HTTP e muito mais. Mesmo com um bom proxy, você pode ser bloqueado se não considerar esses fatores.

1. Mascarando o modo headless

O Playwright em modo headless tem características que são facilmente identificáveis: valores específicos de navigator.webdriver, ausência de plugins, tamanhos de tela não padrão. Use a biblioteca playwright-stealth para mascarar:

# Python: instalação
# pip install playwright-stealth

from playwright.sync_api import sync_playwright
from playwright_stealth import stealth_sync

with sync_playwright() as p:
    browser = p.chromium.launch(
        proxy={
            "server":   "http://residential.proxyprovider.com:8888",
            "username": "user",
            "password": "pass"
        }
    )
    page = browser.new_page()
    stealth_sync(page)  # aplicando a máscara
    
    page.goto("https://bot.sannysoft.com")  # teste de detecção de bot
    browser.close()

2. User-Agent e viewport realistas

context = browser.new_context(
    proxy={
        "server":   "http://proxy.example.com:8080",
        "username": "user",
        "password": "pass"
    },
    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    viewport={"width": 1920, "height": 1080},
    locale="pt-BR",
    timezone_id="Europe/Lisbon"  # deve coincidir com a geolocalização do proxy!
)

3. Imitação do comportamento humano

import time
import random

# Atrasos aleatórios entre ações
def human_delay(min_ms=500, max_ms=2000):
    time.sleep(random.randint(min_ms, max_ms) / 1000)

page.goto("https://example.com")
human_delay()

# Rolagem suave em vez de instantânea
page.evaluate("window.scrollBy({top: 500, behavior: 'smooth'})")
human_delay(300, 800)

# Movimento do mouse antes do clique
page.mouse.move(100, 200)
human_delay(100, 300)
page.mouse.move(300, 400)
human_delay(100, 200)
page.click("button#submit")

4. Coincidência do fuso horário com a geolocalização do proxy

Isso é frequentemente ignorado, mas sistemas de proteção contra bots verificam a correspondência: se seu proxy é de Lisboa, mas o navegador mostra o fuso horário UTC-8 (Los Angeles) — isso é um sinal vermelho. Sempre defina timezone_id de acordo com a geolocalização do proxy utilizado.

Erros comuns e como corrigi-los

Ao trabalhar com proxies no Playwright, os desenvolvedores frequentemente enfrentam os mesmos problemas. Vamos analisar cada um com uma solução específica.

Erro 1: ERR_PROXY_CONNECTION_FAILED

Causa: Endereço ou porta do proxy incorretos, proxy indisponível, credenciais incorretas.
Solução: Verifique a disponibilidade do proxy através do curl antes de iniciar o Playwright:

# Verificação do proxy via curl
curl -x http://user:[email protected]:8080 https://api.ipify.org

Erro 2: SOCKS5 não aceita autenticação

Causa: O Playwright (Chromium) tem suporte limitado para SOCKS5 com autenticação via username/password.
Solução: Use proxies HTTP com autenticação ou configure um túnel SOCKS5 local via ssh -D sem senha.

Erro 3: Proxy funciona, mas o site ainda bloqueia

Causa: Proxies de data center estão em listas negras; modo headless não está mascarado; frequência de solicitações muito alta.
Solução: Mude para proxies residenciais ou móveis, adicione playwright-stealth, aumente os atrasos entre as solicitações.

Erro 4: Vazamento do IP real (DNS leak)

Causa: Solicitações DNS podem contornar o proxy.
Solução: O Playwright, por padrão, direciona DNS através do proxy ao usar proxies HTTP. Mas para verificar, use https://dnsleaktest.com no navegador headless.

Erro 5: Trabalho lento com proxy

Causa: Proxies residenciais são mais lentos que os de data center; grande distância até o servidor proxy.
Solução: Escolha proxies em locais geograficamente próximos. Para tarefas sem requisitos rigorosos de anonimato, use proxies de data center — eles são significativamente mais rápidos.

Conclusão e recomendações

Configurar proxies no Playwright não é uma tarefa única, mas parte da arquitetura da sua ferramenta de automação. O tipo de proxy escolhido corretamente, a rotação de IP adequada e a máscara do modo headless juntas proporcionam um funcionamento estável mesmo em sites com proteção agressiva contra bots.

Vamos resumir a escolha do tipo de proxy para tarefas específicas:

• Scraping de dados abertos sem proteção rigorosa — proxies de data center rápidos são adequados.
• Marketplaces (Wildberries, Ozon), agregadores de notícias — são necessários proxies residenciais com rotação.
• Redes sociais (Instagram, Facebook, TikTok) e sites com Cloudflare — apenas proxies móveis ou residenciais.
• Teste de geolocalização — qualquer tipo de proxy no país necessário, o importante é a coincidência do fuso horário.
• Scraping em massa com alta frequência — proxies residenciais rotativos com endpoint de gateway.

Se você está construindo um sistema de scraping ou testes automatizados no Playwright e precisa de um funcionamento estável sem bloqueios, recomendamos considerar proxies residenciais — eles oferecem um alto nível de confiança por parte dos sites e suportam rotação de IP através de um único endpoint, o que simplifica a integração com o Playwright em apenas algumas linhas de código.