web-automation-core

Camada de abstração para automação web em Python — ações seguras, waits inteligentes e erros descritivos sobre Selenium ou Playwright.

---

O problema

Usar Selenium ou Playwright diretamente resulta em código repleto de time.sleep(), try/except genéricos e mensagens de erro inúteis. Qualquer automação de tamanho real vira um espaguete instável.

web-automation-core resolve isso com uma camada limpa, testável e independente de driver, que torna automações web robustas por padrão.

---

Instalação

# Biblioteca base
pip install web-automation-core

# Com Selenium
pip install "web-automation-core[selenium]"

Ou em modo de desenvolvimento:

git clone https://github.com/seu-usuario/web-automation-core.git
cd web-automation-core
pip install -e ".[dev]"

---

Conceitos fundamentais

Conceito	Descrição
BaseDriver	Interface abstrata — qualquer driver implementa este contrato
WebActions	Ações seguras: safe_click, safe_fill, safe_get, safe_text
SmartWaiter	Esperas inteligentes por elemento, texto, condição e página
Exceções tipadas	ElementoNaoEncontradoError, TimeoutDeEsperaError, AcaoFalhouError

---

Uso rápido

from web_automation_core import WebActions
from web_automation_core.selenium_driver import SeleniumDriver

with SeleniumDriver(headless=True) as driver:
    actions = WebActions(driver, timeout=15.0)

    # Navega e aguarda carregamento completo
    actions.safe_get("https://exemplo.com/login")

    # Preenche campos com segurança (aguarda aparecer antes)
    actions.safe_fill("#usuario", "meu_usuario")
    actions.safe_fill("#senha", "minha_senha")

    # Clica no botão (com retry automático do waiter)
    actions.safe_click("#btn-entrar")

    # Lê o texto de um elemento
    nome = actions.safe_text(".nome-usuario")
    print(f"Logado como: {nome}")

---

SmartWaiter — esperas inteligentes

from web_automation_core.waiter import SmartWaiter

waiter = SmartWaiter(driver, timeout_padrao=10.0)

# Aguarda elemento aparecer no DOM
waiter.aguardar_elemento("#resultado")

# Aguarda spinner de loading sumir
waiter.aguardar_elemento_sumir(".loading-spinner")

# Aguarda página carregar completamente (readyState)
waiter.aguardar_pagina_carregar()

# Aguarda texto específico no elemento
waiter.aguardar_texto_no_elemento(".status", "Concluído")

# Condição arbitrária
waiter.aguardar_condicao(
    lambda: driver.elemento_existe(".modal-confirmacao"),
    mensagem="Modal não abriu",
    timeout=5.0,
)

---

Erros descritivos

from web_automation_core.errors import (
    ElementoNaoEncontradoError,
    TimeoutDeEsperaError,
    AcaoFalhouError,
)

try:
    actions.safe_click("#botao-inexistente", timeout=5.0)
except TimeoutDeEsperaError as e:
    print(f"Timeout: {e}")          # inclui seletor e duração
except AcaoFalhouError as e:
    print(f"Ação falhou: {e}")      # inclui causa original

---

Criando seu próprio driver

from web_automation_core.driver import BaseDriver

class PlaywrightDriver(BaseDriver):
    def abrir(self, url: str) -> None: ...
    def fechar(self) -> None: ...
    def elemento_existe(self, seletor: str) -> bool: ...
    # ... implementar os demais métodos abstratos

A biblioteca funciona com qualquer implementação — sem lock-in.

---

Executar os testes

pytest tests/ -v --cov=web_automation_core

Os testes usam mocks — nenhum browser real é necessário para rodar a suíte.

---

Estrutura do projeto

web-automation-core/
├── web_automation_core/
│   ├── driver.py          # BaseDriver (interface abstrata)
│   ├── actions.py         # WebActions (safe_click, safe_fill...)
│   ├── waiter.py          # SmartWaiter (esperas inteligentes)
│   ├── errors.py          # Exceções tipadas
│   └── selenium_driver.py # Implementação Selenium
├── tests/
│   ├── test_actions.py
│   └── test_waiter.py
└── examples/
    └── exemplo_selenium.py

---

Roadmap

• Implementação Playwright nativa
• safe_select para campos <select>
• Captura automática de screenshot em falhas
• Suporte a iFrames
• Integração com botflow (step de automação web)

---

Licença

MIT © Seu Nome