O que é sistema reptil e como ele funciona na prática
Sistema reptil é uma estrutura de automação de testes baseada em Python que permite escrever cenários de teste de forma mais legível. Não é um framework completo por si só; ele depende do pytest como motor de execução e do requests para fazer chamadas HTTP. A ideia principal é separar o que você quer testar (os passos) de como você quer testar (a infraestrutura).
Vantagens do sistema reptil
O maior ganho é que a organização do código muda completamente quando você para de misturar lógica de negócio com afirmações de teste. Em vez de escrever tudo junto, você cria classes que representam ações e outras que representam o estado esperado. Quando alguém lê o teste, vê imediatamente o que está sendo validado. Testes escritos dessa forma tendem a durar mais tempo sem manutenção pesada. Se a URL de um endpoint mudar, você atualiza em um único lugar, não em trinta arquivos espalhados.
Instalação
A instalação é simples. Use pip install sistema-reptil. O pacote já traz as dependências principais, mas se você for rodar os exemplos, talvez precise instalar o playwright também. O playground do pacote fica em sistema-reptil/reptil-playground.
Como estruturar um projeto
A estrutura básica que eu uso é esta: tests/ actions/ states/ conftest.py test_api.py
Dentro de actions/ você coloca classes que herdam de ReptilAction. Cada método representa uma ação que o sistema pode executar. Dentro de states/ ficam as classes que herdam de ReptilState, e cada uma delas contém métodos que fazem as verificações. Um exemplo mínimo de ação:
from reptil import ReptilAction class LoginAction(ReptilAction): def login(self, email, senha): return self.request.post('/login', json={'email': email, 'senha': senha}) E um exemplo mínimo de estado:
from reptil import ReptilState class AutenticadoState(ReptilState): def deve_retornar_token(self, response): assert response.status_code == 200 assert 'access_token' in response.json()
👉 Clique no botão abaixo para saber mais sobre o assunto!
Escrevendo o primeiro teste
Depois de criar as classes de ação e estado, você monta o teste usando o decorator @reptil.given. Ele recebe uma instância da ação e uma instância do estado, e faz a execução automaticamente. @reptil.given(LoginAction(), AutenticadoState()) def test_login_valido(context): context.execute('login', email='usuario@teste.com', senha='123456')
O contexto dentro da função é apenas um gerenciador que orquestra a chamada da ação e a verificação do estado. Você não precisa chamar assert manualmente, o próprio sistema reptil cuida disso.
Problema real que eu encontrei
Num projeto interno, tínhamos um endpoint que retornava dados paginados com um campo "total" que às vezes era um inteiro e às vezes era uma string. Isso acontecia dependendo do tamanho da resposta. Quando eu coloquei o sistema reptil para rodar, o teste falhava de forma intermitente porque a classe de estado esperava um inteiro. A solução foi criar um método de normalização dentro da ação que converte tudo antes de passar para o estado. Adicionei um método normalize_total no LoginAction que verificava o tipo e fazia a conversão. Depois disso, o teste estabilizou e parou de falhar aleatoriamente. Isso me levou a entender que o sistema reptil não resolve problemas de inconsistência de API. Ele apenas organiza a verificação, mas a qualidade dos dados recebidos ainda depende de você.
Pegadinhas comuns
Primeiro: não use o sistema reptil para testes de UI se você não tiver uma instância do serviço rodando localmente. O package foi pensado para integração com APIs REST, não para interações com navegador. Se você tentar usar com Selenium, vai precisar escrever muito código extra para fazer funcionar. Segundo: o cache de sessões do requests pode causar resultados inconsistentes se você não configurar explicitamente. Eu sempre passo allow_redirects=False e expiração de sessão de 30 segundos nos testes de integração. Sem isso, o sistema reptil reutiliza sessões antigas e os testes não refletem o comportamento real do usuário.
Limitações que ninguém mentiona
O sistema reptil tem um problema sério com testes paralelos. Como ele mantém estado entre ações na mesma instância da classe, rodar múltiplos testes ao mesmo tempo gera colisão de dados. Se você precisa de paralelização, terá que usar múltiplos workers e garantir que cada worker tenha suas próprias instâncias de ação e estado. Isso aumenta a complexidade e reduz o benefício de velocidade que o paralelismo promete. Outro ponto: a curva de aprendizado não é zero. Pessoas que nunca escreveram testes em Python podem levar uma semana inteira para entender como montar a hierarquia de ações e estados corretamente. O pacote não tem um gerador de esqueleto automático, então todo mundo começa do zero escrevendo as classes manualmente.
Alternativas
Se o seu foco é apenas validar APIs de forma rápida sem toda essa estrutura, o httpx com o pytest já resolve 90% do caso. A diferença é que você perde a separação de responsabilidades que o sistema reptil oferece. Se o projeto é pequeno, vale a pena não usar. Se o projeto cresce e os testes viram uma bagunça, aí sim faz sentido migrar para sistema reptil. Também existe o requests-mock, que é mais leve mas menos organizado. Eu já vi times usarem requests-mock em projetos médios e não sentirem falta do sistema reptil. A escolha depende do tamanho do projeto e da disciplina da equipe.
Conclusão prática
Sistema reptil é útil quando você tem muitos cenários de teste e precisa manter a clareza. Ele não é mágico. Ele não resolve problemas de API ruim, não acelera testes isolados e não substitui boas práticas de teste. Mas quando bem aplicado, ele organiza o caos que surge naturalmente em projetos grandes de integração.
