Skip to content

playwright.md

Latest commit

 

History

History
313 lines (220 loc) · 7.3 KB

playwright.md

File metadata and controls

313 lines (220 loc) · 7.3 KB

🎭 Configuração do Playwright - Motor de Automação Web

📖 Visão Geral

O arquivo playwright.py fornece uma interface completa e robusta para gerenciar navegadores Playwright no projeto PDF Conversion. Ele suporta múltiplos navegadores e oferece uma API fácil de usar.

🌐 Navegadores Suportados

Navegador Identificador Descrição
Chromium "chromium" ✅ Padrão - Base do Chrome/Edge
Firefox "firefox" Motor Gecko do Firefox
WebKit "webkit" Motor do Safari

🚀 Uso Básico

1️⃣ Forma Simples (Context Manager)

from pdf_conversion.config.playwright import get_browser

async with get_browser() as manager:
    page = await manager.new_page()
    await page.goto("https://example.com")
    # O navegador fecha automaticamente ao sair do context

2️⃣ Usando BrowserManager Diretamente

from pdf_conversion.config.playwright import BrowserManager

manager = BrowserManager(browser_type="chromium", headless=True)
await manager.start()

page = await manager.new_page("https://example.com")
# ... use a página ...

await manager.close()

🎯 Exemplos Práticos

Trocar de Navegador

# Usar Firefox
async with get_browser(browser_type="firefox") as manager:
    page = await manager.new_page()
    await page.goto("https://example.com")

# Usar WebKit
async with get_browser(browser_type="webkit") as manager:
    page = await manager.new_page()
    await page.goto("https://example.com")

Modo Debug (Visível e Lento)

# Navegador visível com slow motion de 500ms entre ações
async with get_browser(headless=False, slow_mo=500) as manager:
    page = await manager.new_page()
    await page.goto("https://example.com")
    await page.click("a")  # Você verá o click acontecendo lentamente

Múltiplas Páginas (Abas)

async with get_browser() as manager:
    page1 = await manager.new_page("https://example.com")
    page2 = await manager.new_page("https://github.com")
    page3 = await manager.new_page("https://python.org")
    
    print(f"Páginas abertas: {len(manager.pages)}")
    
    # Fechar uma página específica
    await manager.close_page(page2)

Salvar PDF

from pdf_conversion.config.playwright import get_browser, save_pdf

async with get_browser() as manager:
    page = await manager.new_page("https://example.com")
    
    # Salva a página como PDF
    pdf_path = await save_pdf(page, "minha_pagina", format="A4")
    print(f"PDF salvo em: {pdf_path}")

Capturar Screenshot

from pdf_conversion.config.playwright import get_browser, screenshot_page

async with get_browser() as manager:
    page = await manager.new_page("https://example.com")
    
    # Screenshot da viewport
    screenshot_path = await screenshot_page(page, "screenshot")
    
    # Screenshot da página inteira
    full_screenshot = await screenshot_page(page, "full_page", full_page=True)

⚙️ Configurações

As configurações vêm do settings.toml e podem ser sobrescritas:

Configurações Padrão (settings.toml)

[default.playwright]
headless = true                # Modo sem interface gráfica
timeout = 30000               # Timeout em milissegundos
viewport_width = 1920         # Largura da viewport
viewport_height = 1080        # Altura da viewport
user_agent = "Mozilla/5.0..." # User agent customizado

Sobrescrever Configurações

# Sobrescrever headless
async with get_browser(headless=False) as manager:
    # Navegador visível
    pass

# Sobrescrever no BrowserManager
manager = BrowserManager(
    browser_type="firefox",
    headless=True,
    slow_mo=1000  # 1 segundo de delay entre ações
)

🔧 Recursos Principais

BrowserManager

manager = BrowserManager(browser_type="chromium", headless=True)

# Propriedades
manager.browser_type_name  # "chromium", "firefox", "webkit"
manager.headless          # True/False
manager.browser           # Instância do Browser
manager.context           # Instância do BrowserContext
manager.pages             # Lista de páginas abertas

# Métodos
await manager.start()              # Inicia o navegador
await manager.close()              # Fecha tudo
await manager.new_page(url)        # Cria nova página
await manager.close_page(page)     # Fecha página específica

Funções Utilitárias

# Context manager rápido
async with get_browser(browser_type="chromium") as manager:
    pass

# Salvar PDF
pdf_path = await save_pdf(page, "filename", format="A4")

# Screenshot
img_path = await screenshot_page(page, "filename", full_page=False)

📁 Diretórios Criados Automaticamente

O BrowserManager cria automaticamente:

  • temp/downloads/ - Arquivos baixados pelo navegador
  • temp/screenshots/ - Screenshots capturados
  • documents/converted_documents/ - PDFs salvos

🎭 Context Manager vs Manual

✅ Recomendado: Context Manager

async with get_browser() as manager:
    page = await manager.new_page()
    # Cleanup automático garantido

⚠️ Manual (use se precisar de controle fino)

manager = BrowserManager()
try:
    await manager.start()
    page = await manager.new_page()
finally:
    await manager.close()  # Você é responsável pelo cleanup

🐛 Modo Debug

Para debugar problemas:

# 1. Navegador visível
async with get_browser(headless=False) as manager:
    pass

# 2. Slow motion (veja as ações acontecendo)
async with get_browser(headless=False, slow_mo=1000) as manager:
    pass

# 3. Screenshots em cada passo
async with get_browser() as manager:
    page = await manager.new_page("https://example.com")
    await screenshot_page(page, "step_1")
    
    await page.click("button")
    await screenshot_page(page, "step_2")

🔐 Features de Segurança

O BrowserManager configura automaticamente:

  • ✅ User-Agent realista
  • ✅ Locale e timezone (pt-BR, America/Sao_Paulo)
  • ✅ Desabilita detecção de automação (--disable-blink-features)
  • ✅ Suporte a downloads
  • ✅ Viewport configurável

📊 Integração com o Projeto

O Playwright está integrado com:

  • Config: Usa settings.playwright do settings.toml
  • Paths: Usa ROOT_DIR e settings.paths para diretórios
  • Ambientes: Respeita configurações de dev/prod

🧪 Testando

Execute o arquivo de exemplo:

# Instale os navegadores primeiro (apenas uma vez)
playwright install

# Execute os exemplos
uv run example_playwright.py

📝 Notas Importantes

  1. Async/Await: Todas as operações do Playwright são assíncronas
  2. Cleanup: Sempre use context managers para garantir fechamento
  3. Timeout: Configure timeouts adequados para operações lentas
  4. Navegadores: Chromium é o mais rápido e confiável
  5. Downloads: Arquivos são baixados em temp/downloads/

🆘 Troubleshooting

Erro: "Executable doesn't exist"

playwright install

Navegador não abre em modo visível

# Force headless=False
async with get_browser(headless=False) as manager:
    pass

Timeout em operações

# Aumente o timeout
page.set_default_timeout(60000)  # 60 segundos

✅ Configuração completa e pronta para uso! 🎭