Skip to main content

Capivara 🦫 — RPA em Python, 100% em português

Deixa que a Capivara faz. Um template low-code de RPA feito para a comunidade Python — do dev que nunca abriu um Python até o dev sênior que precisa de um atalho produtivo. As bibliotecas complexas (Selenium, pandas, requests...) viraram funções em português e todo o processo aparece colorido no terminal.

🗃️ Web:   navegador.abrir_url(...)
         navegador.escrever_texto(...)
         navegador.clicar_elemento(...)

📊 Dados: ler_csv(...) -> filtrar_linhas(...) -> escrever_excel(...)

📦 ARQ:   listar_arquivos(...) · baixar_arquivo(...) · extrair_zip(...)

🌐 API:   api_get(...) · api_post(...) · api_upload(...) · api_download(...)

✉️ Email: enviar_email(...) · enviar_email_html(...)

🧰 Útil:  validar_cpf(...) · gerar_senha(...) · notificacoes.enviar_slack(...)

Comunidade: sugestões, RFCs e exemplos ficam em capivara-rpa/capivara-community. A main deste repositório é a versão estável; a branch next recebe as propostas aceitas antes do próximo release.


📖 Índice

  1. Para quem é este template
  2. Tecnologias
  3. Estrutura de pastas
  4. Pré-requisitos
  5. Instalação
  6. Como executar
  7. Configuração (.env)
  8. Criando seu primeiro robô
  9. Utilidades prontas (+50 funções)
  10. Modo dev vs prod (headless)
  11. Rodando no Docker
  12. Control Room (orquestrador)
  13. Monitor de execuções (trace)
  14. Testes automatizados
  15. Dicas para a comunidade
  16. Documentação complementar

Para quem é este template

Perfil O que encontra aqui
Entusiasta / iniciante Tutorial do zero abaixo + funções prontas em português. Não precisa decorar Selenium.
Dev Pleno Motor core/ pronto para produção: logs, retry, headless, .env, Docker.
Dev Sênior / Especialista Arquitetura leve, tudo extensível em core/, sem mágica obscura.

Tecnologias

  • Python 3.11+
  • Selenium 4 (automação web) + Selenium Manager (driver automático — não precisa instalar ChromeDriver)
  • pandas + openpyxl (planilhas)
  • requests (APIs)
  • Loguru + rich (logs coloridos e tabelas bonitas no terminal)
  • python-dotenv (configurações e segredos)

Estrutura de pastas

capivara/
├── app/                    # 🔌 Componentes da aplicação (o SEU robô)
│   ├── main.py             #    Ponto de entrada / orquestrador
│   └── fluxos/             #    Cada tarefa de negócio em um arquivo
├── capivara_rpa/           # 📚 Fachada pública da biblioteca (pip install capivara-rpa)
├── core/                   # ⚙️ Motor low-code reutilizável
│   ├── rpa/                #    browser · dados · arquivo · api · email · banco
│   │                       #    texto · validacao · seguranca · sistema · notificacoes
│   ├── monitor/            #    Painel de trace das execuções (SQLite + web local)
│   ├── control_room/       #    Orquestrador: máquinas, processos, jobs e agente
│   ├── logger.py           #    Logging colorido (Loguru)
│   ├── robo.py             #    Orquestrador dos fluxos
│   └── tratador.py         #    @passo, @tentar_novamente e exceções
├── settings/               # 🎛️ Configurações do projeto
│   ├── parametros.py       #    Parâmetros centrais (dev/prod, tempos, paths)
│   ├── ambiente.py         #    Carrega variáveis do .env
│   └── .env.example        #    Modelo de configuração
├── data/                   # 📁 Documentação e insumos
│   ├── docs/               #    Guias e arquitetura
│   ├── input/              #    Arquivos de entrada dos robôs
│   ├── output/             #    Resultados gerados
│   └── logs/               #    Logs do robô (rotação automática)
├── scripts/                # 🛠️ Helpers: install, run, monitor, control_room
├── .env.example
├── .gitignore
├── Dockerfile
├── pyproject.toml
└── requirements.txt

Regra de bolso: app/ é do seu robô, core/ é do motor. Você muda app/ e settings/; o core/ já vem pronto.


Pré-requisitos

  • Python 3.11+ (python.org)
  • Google Chrome instalado
  • (Opcional) Docker para rodar em servidor

O ChromeDriver é baixado automaticamente pelo Selenium Manager na primeira execução.


Instalação

Opção rápida (scripts)

# Linux / macOS
bash scripts/install.sh

# Windows
scripts\install.bat

Passo a passo manual

# 1. Acesse a raiz do projeto
cd capivara

# 2. Crie um ambiente virtual isolado
python -m venv .venv

# 3. Ative-o
source .venv/bin/activate        # Linux / macOS
.venv\Scripts\activate           # Windows

# 4. Instale as dependências
pip install -r requirements.txt

# 5. (Opcional) crie o arquivo de configuração
cp .env.example .env

💡 Windows: use py -m venv .venv se python não existir no PATH.

Usar como biblioteca (PyPI)

A distribuição pública é capivara-rpa (import capivara_rpa, CLI capivara):

pip install capivara-rpa              # base: texto, validação, API, arquivos...
pip install "capivara-rpa[web]"       # + Selenium/Navegador
pip install "capivara-rpa[all]"       # kit completo (web + dados + cofre + filas)
from capivara_rpa import texto, validacao

texto.slug("Relatório de Clientes 2026")   # 'relatorio-de-clientes-2026'
validacao.validar_cpf("529.982.247-25")    # True

Para automação web:

from capivara_rpa import Navegador

with Navegador() as navegador:
    navegador.abrir_url("https://exemplo.com.br")
    navegador.escrever_texto("#busca", "Capivara")
    navegador.clicar_elemento("button[type=submit]")

Instale só o que precisar com os extras: web (Selenium), dados (pandas), cofre (criptografia), pacotes (zip com senha), interacao (pyperclip), control-room, all ou keyring. O import da raiz é lazy: quem usa apenas texto/validacao não carrega Selenium nem pandas.


Como executar

# Roda TODOS os fluxos de exemplo
python app/main.py

# Roda só um fluxo
python app/main.py --web          # navegador (Google)
python app/main.py --dados        # pandas (planilha)

# Ou via script
bash scripts/run.sh               # Linux / macOS
scripts\run.bat --dados           # Windows

Você verá algo assim no terminal:

10:47:07.646 | DEBUG    | Logger configurado para o processo 'capivara'. Arquivo: ...
━━━━━━━━━━━━━━━━━━━━━━━━━
  Capivara 🦫 — Deixa que a Capivara faz.
━━━━━━━━━━━━━━━━━━━━━━━━━
10:47:12.747 | SUCCESS  | Filtro aplicado: 5 de 10 linhas
10:47:13.628 | SUCCESS  | Planilha com 3 abas salva: data/output/relatorio_clientes.xlsx
10:47:13.634 | SUCCESS  | ✓ Fluxo concluído com sucesso: Tratamento de dados (pandas)

Configuração (.env)

Copie .env.example para .env e ajuste:

AMBIENTE=dev                 # dev (janela) | prod (headless)
HEADLESS=false
SITE_DEMO=https://www.google.com.br/
USUARIO=
SENHA=
API_BASE_URL=
API_TOKEN=
SMTP_SERVIDOR=
SMTP_PORTA=465
SMTP_USUARIO=
SMTP_SENHA=
SMTP_ORIGEM=
NOME_LOG=rpa.log

🔒 Nunca commite o arquivo .env (ele está no .gitignore). Credenciais sempre por variável de ambiente, nunca hardcoded no código.


Criando seu primeiro robô

  1. Crie um arquivo em app/fluxos/, ex.: app/fluxos/meu_fluxo.py:
"""Meu primeiro fluxo: preencher um formulário."""
from settings.parametros import SITE_DEMO


def preencher_formulario(navegador) -> bool:
    navegador.abrir_url(SITE_DEMO)
    navegador.escrever_texto("#nome", "Fulano de Tal")
    navegador.escrever_texto("#email", "fulano@exemplo.com")
    navegador.selecionar_opcao("#estado", valor="SP")
    navegador.marcar_checkbox("#termos", marcar=True)
    navegador.clicar_elemento("//button[@type='submit']")
    navegador.capturar_tela("formulario_enviado")
    return True
  1. Registre o fluxo em app/main.py:
FLUXOS = {
    "web": ("Busca no Google (navegador)", buscar_no_google),
    "dados": ("Tratamento de dados (pandas)", tratar_planilha),
    "form": ("Preencher formulário", preencher_formulario),  # 👈 novo
}
  1. Execute:
python app/main.py --form

Pronto: o robô abre o site, preenche, mostra cada passo colorido no terminal e salva prints em data/output/. Isso é RPA low-code na prática.


Utilidades prontas (+50 funções)

Além do navegador e das planilhas, o motor ganhou módulos para o dia a dia do robô. Tudo em português, com log automático e sem dependência nova:

Módulo Arquivo O que resolve
texto core/rpa/texto.py limpar, normalizar, slug, extrair e-mails/URLs/números, regex, similaridade
validacao core/rpa/validacao.py CPF/CNPJ (validar, formatar, gerar), CEP, telefone, e-mail, datas úteis e moeda BR
banco core/rpa/banco.py SQLite: conectar, consultar, inserir/atualizar/apagar, DataFrame, importar/exportar CSV
seguranca core/rpa/seguranca.py senha/token, SHA-256, Base64, Fernet (criptografia), máscara e comparação segura
sistema core/rpa/sistema.py executar comandos, abrir pastas/arquivos, esperar arquivo, variáveis de ambiente e notificação desktop
notificacoes core/rpa/notificacoes.py webhooks para Slack, Teams, Discord, Telegram e webhook genérico
arquivo core/rpa/arquivo.py + JSON/INI, hash, comparar, últimas linhas, juntar/dividir e tamanho
dados core/rpa/dados.py + renomear, deduplicar, preencher, ordenar, pivotar, melt, Markdown e percentual
api core/rpa/api.py + PATCH/HEAD, upload multipart e download para arquivo
email core/rpa/email.py + HTML, CC/BCC, Reply-To e teste de SMTP
Navegador core/rpa/browser.py + texto/HTML da página, tabelas, cookies, abas, alertas, JS e captura de elemento
tracktab core/rpa/tracktab.py + buscar/obter seletor, listar, CSV, resumo e combinar exports
from core.rpa import banco, notificacoes, seguranca, texto, validacao

texto.slug("Relatório de Clientes 2026")        # 'relatorio-de-clientes-2026'
validacao.validar_cpf("529.982.247-25")         # True
seguranca.gerar_senha(20)                       # senha forte
notificacoes.enviar_slack(webhook, "Robô terminou!")

con = banco.conectar("data/input/dados.db")
banco.consultar(con, "SELECT * FROM clientes WHERE uf = ?", ("SP",))

A lista completa, com assinaturas e exemplos, está em data/docs/CATALOGO_FUNCOES.md.


Modo dev vs prod (headless)

Ambiente Janela do navegador Uso típico
AMBIENTE=dev (padrão) ✅ Visível Desenvolvimento e debug
AMBIENTE=prod ❌ Oculta (headless) Servidor, agendador, Docker

Mude o ambiente com o .env ou variável de ambiente:

AMBIENTE=prod python app/main.py

Rodando no Docker

docker build -t meurobo .
docker run --rm meurobo

O Dockerfile já instala o Chrome, roda em headless (AMBIENTE=prod) e os resultados ficam em data/output/ dentro do container.

💡 Para pegar os arquivos gerados, monte um volume: docker run --rm -v "$PWD/data/output:/app/data/output" meurobo


Control Room (orquestrador)

Um Orchestrator estilo UiPath: um painel online onde você cadastra máquinas, mantém um catálogo de processos (seus robôs) e dispara jobs em máquinas específicas. Os agentes instalados em cada máquina fazem o heartbeat, buscam os jobs e devolvem o resultado — que vira uma trace no painel de monitoramento.

   Control Room (servidor)                 Agente (em cada máquina)
  ┌────────────────────────┐   jobs     ┌──────────────────────────┐
  │ máquinas · processos   │ ─────────► │ registra · heartbeat     │
  │ jobs · disparo         │ ◄───────── │ executa fluxo · resultado│
  └────────────────────────┘  heartbeat └──────────────────────────┘

Tudo com SQLite + biblioteca padrão (o agente usa requests), sem novas dependências.

# 1. Popular com máquinas/processos/jobs de exemplo e subir a Control Room
bash scripts/control_room.sh --exemplos     # Linux / macOS
scripts\control_room.bat --exemplos         # Windows

# 2. Abra:  http://localhost:8765            (Control Room)
#           http://localhost:8765/monitor/   (trace das execuções)

# 3. Simule uma máquina (abra um terminal por máquina)
python -m core.control_room.agente --maquina maquina-01
python -m core.control_room.agente --maquina maquina-02 --tags "rh,sp"
bash scripts/agente.sh --maquina maquina-03 --tags "mac"   # atalho

Sem terminal aberto — dá para deixar o agente rodando como serviço: no macOS, bash scripts/instalar_agente_mac.sh instala um LaunchAgent (sobe junto com a sessão, reconecta sozinho; --remover desinstala); no Windows, crie uma Tarefa Agendada apontando para scripts\agente.bat.

No painel: clique em Executar num processo (ou “+ Novo job”), escolha a máquina (ou “qualquer”), e o agente que estiver livre pega o job. O resultado e o passo a passo aparecem na hora — cada job tem link para o seu trace.

O painel tem as abas: Jobs (Control Room), Dispositivos, Agendamentos, Automações, Filas, Assets e Acessos (usuários, papéis e permissões).

  • Login / RBAC (multiempresa) — por padrão a Control Room é aberta (CONTROL_ROOM_AUTH=false, ideal para dev/LAN). Ligue CONTROL_ROOM_AUTH=true para exigir login: o primeiro start cria o admin padrão (ADMIN_EMAIL/ADMIN_SENHA, padrão admin@rpa.local / admin — troque em produção). A aba Acessos gerencia usuários, papéis e permissões granulares (jobs.disparar, assets.gerir, usuarios.gerir…); a sessão é um cookie HttpOnly com validade de SESSAO_HORAS.

    CONTROL_ROOM_AUTH=true ADMIN_EMAIL=eu@empresa.com ADMIN_SENHA=segredo \
        python -m core.control_room.servidor
    
  • Pools por tag — cadastre tags nas máquinas (--tags "sp,financeiro") e use o campo Requisito (tag) ao disparar um job. Só uma máquina com a tag pega o job, permitindo distribuir robôs por pool.

    python -m core.control_room.agente --maquina maquina-02 --tags "rh,sp"
    
  • Token por máquina — cada máquina pode ter o seu próprio token (emitido em POST /api/orq/maquinas/<nome>/token ou na aba Acessos), revogável individualmente. O agente usa com --token; o CONTROL_ROOM_TOKEN global continua valendo como coringa.

  • Agendamentos (triggers) — dispare jobs automaticamente por intervalo (a cada N minutos), diário (HH:MM) ou cron (expressão de 5 campos, ex.: */15 9-18 * * seg-sex). Cada agendamento escolhe o robô, onde rodar (máquina e/ou tag), os dias da semana e se roda em fins de semana e feriados nacionais (cálculo próprio, sem dependência: core/control_room/feriados.py). Na aba dá para pausar/ativar, executar na hora e remover. O servidor verifica os vencidos num loop de fundo (INTERVALO_TRIGGERS no .env, 15s).

  • Automações (pacotes de robô) — publica um robô pela UI de duas formas:

    • .zip — envie um .zip com o manifesto rpa.json na aba Automações e a Control Room extrai em app/robos/<nome>/ e cadastra o processo no catálogo automaticamente (senha AES opcional). Dá para remover (apaga arquivos + catálogo).
    • repositório Git — informe a URL HTTPS pública de um repo que tenha o rpa.json na raiz (+ branch/tag opcional) e clique em Instalar do Git. A Control Room clona (shallow) e instala igual ao .zip; robôs de Git ganham o botão Atualizar (clona de novo e substitui com um clique). Requer o git instalado na máquina. Só repositórios públicos por enquanto.

    O mesmo fluxo existe por CLI (python -m core.control_room.pacote): empacotar, instalar e instalar-git <url> [--ref]. Exemplo de robô público para testar: arthurfs11/robo-teste-popup.

  • Assets / credenciais (v2) — guarde segredos na Control Room e busque-os no fluxo (sem espalhar senha pelo código). Cada asset tem tipo (segredo ou texto), usuário opcional, versão e histórico. Assets segredo são cifrados no banco (Fernet). A chave vem de VAULT_CHAVE (.env), do chaveiro do sistema (VAULT_USAR_KEYRING=true + extra [keyring]) ou de data/vault.key se você não definir nenhum. Na UI eles aparecem mascarados (••••••••) e o agente recebe o valor real:

    from core.rpa import vault
    
    usuario = vault.obter("portal_usuario")   # valor simples (ou agente.asset(...))
    senha = vault.exigir("portal_senha")      # igual, mas falha se não existir
    
    cred = vault.buscar_credencial("portal")  # {usuario, senha, tipo, versao}
    vault.rotacionar("portal", "nova-senha")  # troca o valor, versão + 1
    
    • Rotação: POST /api/orq/assets/<nome>/rotacionar (ou vault.rotacionar) incrementa a versão e guarda a anterior em asset_versoes.
    • Permissões por processo: POST /api/orq/assets/<nome>/permissoes — sem nenhuma permissão o asset é aberto; com permissões, só o processo autorizado lê (via ?processo_id= na rota GET /api/orq/credenciais/<nome>).
    • Auditoria (append-only): toda criação, leitura, rotação e permissão entra na tabela auditoria; veja na aba Assets do painel ou em GET /api/orq/auditoria?recurso=&ator=. Exporte com o botão Exportar CSV (GET /api/orq/auditoria/exportar) e descarte os antigos com POST /api/orq/auditoria/expurgar (retenção automática de RETENCAO_AUDITORIA_DIAS, padrão 90, expurgada ~1x/hora).
    • Segredos que por acaso escapem para uma mensagem de log são mascarados automaticamente pelo logger (core/logger.py).
  • Alertas de SLA — jobs em execução há mais de LIMITE_JOB_SEGUNDOS (padrão 300s) viram alerta (GET /api/orq/alertas e faixa de aviso no topo do painel), sinalizando robôs travados.

  • Filas / datapool (estilo UiPath Queues) — crie um pool de itens e deixe os robôs consumirem um por um, com retry e status:

    from core.rpa import fila
    
    fila.criar("clientes", descricao="NFs de hoje", processo="Dados — Tratar planilha")
    fila.adicionar("clientes", [
        {"nome": "ACME", "uf": "SP"},
        {"nome": "XPTO", "uf": "RJ"},
    ], referencia_campo="nome")
    

    O agente consome a fila com --fila (o job nasce automaticamente do processo executor e o fluxo recebe item):

    python -m core.control_room.agente --maquina maquina-01 --fila clientes
    
    def meu_fluxo(navegador=None, item=None, agente=None):
        dados_item = item["dados"]   # {"nome": "ACME", "uf": "SP"}
        if agente and agente.cancelado():
            return False             # job cancelado na Control Room
    

    Internamente há claim atômico (sem dois agentes pegarem o mesmo item), prioridade (inclusive por item, editável na UI), contagem de tentativas (max_retentativas, padrão 3) e estados novo / em_processamento / concluído / falhou / abandonado. A aba Filas permite pausar/ativar, filtrar itens por status, definir a prioridade de cada item e apontar vários processos executores — distribuídos em round-robin. Jobs podem ser cancelados (pendente ou em execução) e têm tela de detalhe com o trace embutido.

  • Pacotes de robô (.zip ou Git) — empacote um robô com um manifesto rpa.json e envie para a Control Room, que instala em app/robos/<nome>/ e já cadastra o processo. Também dá para instalar direto de um repositório Git público e depois atualizar re-clonando:

    python -m core.control_room.pacote empacotar minha_pasta_robo/ --senha "opcional"
    python -m core.control_room.pacote instalar meu_robo.zip
    python -m core.control_room.pacote instalar-git https://github.com/usuario/meu-robo.git --ref main
    

    rpa.json mínimo:

    {
      "nome": "cliente_mock",
      "versao": "1.0.0",
      "entrada": "main.py",
      "funcao": "rodar",
      "usa_navegador": false
    }
    

    Se o robô tiver um requirements.txt próprio, o agente cria um .venv isolado para ele na hora da execução: cria a venv, atualiza o pip, instala as dependências e roda o robô nesse ambiente (assim dependências de robôs não conflitam). Desligue com RPA_INSTALAR_DEPENDENCIAS=false. Comece pelo exemplo em TEMPLATE/.

  • Rede + token + TLS — para rodar agentes em outras máquinas, suba a Control Room com HOST_CONTROL_ROOM=0.0.0.0 (aceita a rede). Se for expor fora de uma rede confiável (VPN/hosted), defina CONTROL_ROOM_TOKEN no .env do servidor e em cada agente (--token ou a mesma variável), e ligue HTTPS com --cert/--chave (ou TLS_CERT/TLS_CHAVE). Sem token, a Control Room fica aberta (ideal para dev/rede local). Só as rotas dos agentes (registrar, buscar job, reportar execução, ler assets) exigem o token — o painel continua acessível no navegador:

    # servidor (com token e HTTPS opcional)
    export HOST_CONTROL_ROOM=0.0.0.0 CONTROL_ROOM_TOKEN="meu-segredo"
    python -m core.control_room.servidor --cert data/cert.pem --chave data/chave.pem
    
    # agente em outra máquina (na mesma rede)
    python -m core.control_room.agente --maquina maquina-02 \
        --control-room https://10.0.0.5:8765 --token "meu-segredo"
    

    Para máquinas em redes diferentes, use um overlay (Tailscale/ZeroTier) em vez de abrir porta no roteador. Guia completo (token, TLS, VPN, firewall): data/docs/REDE.md. Os painéis usam SSE (/api/orq/eventos e /api/eventos) para atualizar em tempo real, com polling como reserva.

O catálogo de processos aponta para fluxos Python (app.fluxos:buscar_no_google), então cadastrar um robô novo é só criar o fluxo e registrá-lo. Para o piloto, o catálogo já vem com dois exemplos.

Bancos em data/orquestrador.db (máquinas/jobs/triggers/assets/filas e identidade) e data/monitor.db (trace), ambos fora do Git. Ajuste porta, host, heartbeat, intervalo dos agendamentos, URL de consumo, token e chave do vault no .env (PORTA_CONTROL_ROOM, HOST_CONTROL_ROOM, SEGUNDOS_OFFLINE, INTERVALO_TRIGGERS, CONTROL_ROOM_URL, CONTROL_ROOM_TOKEN, VAULT_CHAVE, CONTROL_ROOM_AUTH, ADMIN_EMAIL, ADMIN_SENHA, SESSAO_HORAS, RETENCAO_AUDITORIA_DIAS, LIMITE_JOB_SEGUNDOS).

Automações de teste (bot_test/)

Para experimentar o orquestrador sem escrever um robô do zero, o template traz a pasta bot_test/ com automações simples que só registram logs (e umas que falham, demoram ou consomem fila de propósito):

python -m bot_test.registrar          # cadastra os robôs de teste no catálogo
python -m bot_test.rodar_local todos  # ou rode localmente, sem Control Room

Depois é só subir um agente e clicar em Executar no painel. Veja o passo a passo completo em bot_test/README.md.

Instaladores (servidor e agente sem Python)

Para rodar a Control Room (e um agente) numa máquina sem Python, gere os binários com PyInstaller — ou use os scripts que montam o pacote completo:

pip install pyinstaller

# macOS/Linux: binários soltos
pyinstaller --noconfirm packaging/control_room.spec   # dist/control_room
pyinstaller --noconfirm packaging/agente.spec         # dist/robo_agente

# macOS: pacote "tudo empacotado" (binários + TrackTab + instalador de serviços)
bash packaging/build_mac.sh                           # dist/RPA-Brasil-macos.zip

# Windows: instalador .exe (Inno Setup) com Control Room + Agente + TrackTab
iscc packaging/inno_setup.iss                         # dist/instalador/control_room_instalador.exe

# ao rodar um binário, defina onde persistir os dados:
RPA_PASTA_DADOS="$HOME/.rpa_brasil" ./dist/control_room

No macOS, o dist/RPA-Brasil/instalar_mac.sh copia tudo para ~/RPA Brasil, cria o .env/data/ e instala Control Room e agente como serviços (LaunchAgents, sobem no login). No Windows, o instalador cria atalhos e oferece iniciar o agente junto com o Windows. O workflow .github/workflows/build-instaladores.yml gera tudo isso no CI a cada tag v*. Detalhes em packaging/README.md.

Extensão TrackTab (seletores com um clique)

A extensão TrackTab (tracktab/) captura os elementos de uma página e exporta XPath (absoluto/relativo e um caminho "amigável") em JSON — ótimo para montar selectores sem ficar inspecionando o HTML no olho. Leia o export no robô:

from core.rpa import tracktab

elementos = tracktab.carregar("data/input/tracktab_exemplo.json")
seletores = tracktab.seletores("data/input/tracktab_exemplo.json", "relativo")
# {"nome": "//div[@id='...']", ...}

Enquanto não estiver na Chrome Web Store, carregue a pasta tracktab/ em chrome://extensions (Modo do desenvolvedor → Carregar sem compactação). Para publicar (instalação de 1 clique):

bash packaging/build_tracktab.sh        # gera dist/tracktab.zip

Passo a passo completo: tracktab/PUBLICAR.md.


Monitor de execuções (trace)

Cansado de caçar o que o robô fez só no terminal? O template traz um painel local que transforma cada execução numa trace: status do robô e o passo a passo de cada ação, atualizando sozinho a cada 2 segundos.

Status acompanhados: iniciado · processando · finalizado · falha · erro de negócio · erro sistêmico · erro crítico.

Tudo roda com SQLite + biblioteca padrão — nenhuma dependência nova.

# 1. Popular o banco com robôs de exemplo (mock) e subir o painel
bash scripts/monitor.sh --exemplos     # Linux / macOS
scripts\monitor.bat --exemplos         # Windows

# 2. Abra no navegador:  http://localhost:8765

Usando nos seus robôs (registro em tempo real):

from core.monitor import Monitor

monitor = Monitor("robo_folha_pagamento")
monitor.passo("Abrindo o portal de RH")
monitor.sucesso("Login realizado")
monitor.erro_negocio("CPF inválido na linha 42")   # ou .finalizar(...) / .falha(...)

Os dados ficam em data/monitor.db (fora do Git). Sem os exemplos, o painel sobe vazio e vai enchendo conforme os robôs rodam.


Testes automatizados

Testes de pytest cobrem o motor do monitor (execuções/passos) e as regras do Control Room (pools por tag, agendamentos, assets cifrados no vault — com tipos, versões, rotação, permissões e auditoria —, filas com retry/claim, pacotes .zip e claim de jobs). Os testes apontam os bancos para um diretório temporário, então nunca tocam em data/*.db.

pip install -e ".[dev]"     # instala pytest + ruff
pytest                      # roda toda a suíte
ruff check app core settings tests

Dicas para a comunidade

  • Selectores: entender XPATH e CSS ajuda muito. Comece com @id, depois //tag[@atributo='valor']. Extraia-os em constantes no topo do arquivo de fluxo.
  • Esperas: prefira aguardar_elemento(...) / aguardar_url_contem(...) a time.sleep(). Em oposição ao sono cego, esperar é determinístico e mais rápido.
  • Retry: use o decorador @tentar_novamente(vezes=3) em passos sujeitos a instabilidade de rede.
  • Passo a passo: use @passo("Descrição") para ver o andamento do robô no log.
  • Segredos: tudo que for senha/token morre no .env, nunca no código.
  • Falhas do Google: em IPs de cloud o Google pode apresentar CAPTCHA. Para bots de produção, prefira AMBIENTE=prod em máquina local ou políticas de WebDriver de verdade (isto é só um template de exemplo).

Documentação complementar


Feito com ❤️ para a comunidade Python Brasil. Contribuições são bem-vindas!

Metadata

Release files for capivara-rpa 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for capivara-rpa 1.2.0
File Size Uploaded Provenance Actions
capivara_rpa-1.2.0.tar.gz 183.2 kB Without provenance Details for capivara_rpa-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for capivara-rpa 1.2.0
File Interpreter ABI Platform Actions
capivara_rpa-1.2.0-py3-none-any.whl Python 3 none any Details for capivara_rpa-1.2.0-py3-none-any.whl

Total release size: 352.2 kB

Release files / capivara_rpa-1.2.0.tar.gz

Download URL capivara_rpa-1.2.0.tar.gz
Size 183.2 kB
Tags Source
SHA-256 checksum
How to use checksums
adfee9034293eef28c46ec3a952b3ef55fe6427e37b4d87cf500351c2424059e
BLAKE2b-256 checksum
How to use checksums
5370d009a227b744846d6f99c8dab863c1e6fb05912fc260be959172ed1d6545
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.15

Release files / capivara_rpa-1.2.0-py3-none-any.whl

Download URL capivara_rpa-1.2.0-py3-none-any.whl
Size 169.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
960edca36a022ba533de2cda1742ddd54f07a6810c9daeb6dc7bc78cfe7a4437
BLAKE2b-256 checksum
How to use checksums
a586c9397ed7fd446c6760f23326d5bed4c8e205c5d3f2ce671804041d715a9e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.15

Security for capivara-rpa 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page