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. Amaindeste repositório é a versão estável; a branchnextrecebe as propostas aceitas antes do próximo release.
📖 Índice
- Para quem é este template
- Tecnologias
- Estrutura de pastas
- Pré-requisitos
- Instalação
- Como executar
- Configuração (.env)
- Criando seu primeiro robô
- Utilidades prontas (+50 funções)
- Modo dev vs prod (headless)
- Rodando no Docker
- Control Room (orquestrador)
- Monitor de execuções (trace)
- Testes automatizados
- Dicas para a comunidade
- 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ê mudaapp/esettings/; ocore/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 .venvsepythonnã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ô
- 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
- 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
}
- 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.shinstala um LaunchAgent (sobe junto com a sessão, reconecta sozinho;--removerdesinstala); no Windows, crie uma Tarefa Agendada apontando parascripts\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). LigueCONTROL_ROOM_AUTH=truepara exigir login: o primeiro start cria o admin padrão (ADMIN_EMAIL/ADMIN_SENHA, padrãoadmin@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 cookieHttpOnlycom validade deSESSAO_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>/tokenou na aba Acessos), revogável individualmente. O agente usa com--token; oCONTROL_ROOM_TOKENglobal 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_TRIGGERSno.env, 15s). -
Automações (pacotes de robô) — publica um robô pela UI de duas formas:
- .zip — envie um .zip com o manifesto
rpa.jsonna aba Automações e a Control Room extrai emapp/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.jsonna 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 ogitinstalado na máquina. Só repositórios públicos por enquanto.
O mesmo fluxo existe por CLI (
python -m core.control_room.pacote):empacotar,instalareinstalar-git <url> [--ref]. Exemplo de robô público para testar:arthurfs11/robo-teste-popup. - .zip — envie um .zip com o manifesto
-
Assets / credenciais (v2) — guarde segredos na Control Room e busque-os no fluxo (sem espalhar senha pelo código). Cada asset tem tipo (
segredooutexto), usuário opcional, versão e histórico. Assetssegredosão cifrados no banco (Fernet). A chave vem deVAULT_CHAVE(.env), do chaveiro do sistema (VAULT_USAR_KEYRING=true+ extra[keyring]) ou dedata/vault.keyse 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(ouvault.rotacionar) incrementa a versão e guarda a anterior emasset_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 rotaGET /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 emGET /api/orq/auditoria?recurso=&ator=. Exporte com o botão Exportar CSV (GET /api/orq/auditoria/exportar) e descarte os antigos comPOST /api/orq/auditoria/expurgar(retenção automática deRETENCAO_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).
- Rotação:
-
Alertas de SLA — jobs em execução há mais de
LIMITE_JOB_SEGUNDOS(padrão 300s) viram alerta (GET /api/orq/alertase 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 recebeitem):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 estadosnovo / 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.jsone envie para a Control Room, que instala emapp/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.jsonmínimo:{ "nome": "cliente_mock", "versao": "1.0.0", "entrada": "main.py", "funcao": "rodar", "usa_navegador": false }
Se o robô tiver um
requirements.txtpróprio, o agente cria um.venvisolado 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 comRPA_INSTALAR_DEPENDENCIAS=false. Comece pelo exemplo emTEMPLATE/. -
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), definaCONTROL_ROOM_TOKENno.envdo servidor e em cada agente (--tokenou a mesma variável), e ligue HTTPS com--cert/--chave(ouTLS_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/eventose/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) edata/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(...)atime.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=prodem máquina local ou políticas de WebDriver de verdade (isto é só um template de exemplo).
Documentação complementar
- 🚀 Guia passo a passo — instalar, configurar, token do dispositivo e subir agentes
- 📋 Catálogo de funções — todas as funções low-code com exemplos
- 🏗️ Arquitetura — como os módulos se relacionam e como estender
- 🌐 Rede, token, TLS e VPN — rodar agentes em outras máquinas com segurança
- 📦 Instaladores — Control Room/agente sem Python (macOS e Windows) e a extensão TrackTab
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.