Se você tem um esquema OpenAPI ou GraphQL, o Schemathesis pode transformá-lo em milhares de casos de teste sem que você precise escrever uma única asserção. Ele lê a especificação, gera entradas "selvagens" e válidas, as dispara em sua API e relata onde as respostas violam o contrato. Este guia explica o que é o Schemathesis, como instalá-lo e executá-lo, o que realmente significa o teste baseado em propriedades e como ele se encaixa ao lado de um fluxo de trabalho de testes funcionais e de contrato no Apidog.
O que é Schemathesis?
Schemathesis é uma ferramenta Python de código aberto que gera testes de API automaticamente a partir de um esquema. Você a aponta para uma definição OpenAPI ou GraphQL, e ela constrói casos de teste a partir dos tipos, formatos e restrições que você já declarou. É construída sobre Hypothesis, a biblioteca de testes baseados em propriedades para Python, e é distribuída sob a licença MIT.
A ideia central é simples. Sua especificação já descreve como deve ser uma requisição e uma resposta válidas. O Schemathesis trata essa descrição como uma fonte da verdade e verifica se sua API em execução realmente a honra. Quando a API retorna um 500, envia uma resposta que viola o esquema declarado ou aceita uma entrada que deveria ter rejeitado, o Schemathesis sinaliza o problema.
Você o executa na linha de comando com schemathesis run (ou o apelido mais curto st run). Há também uma integração Python se você quiser controlá-lo a partir do pytest em vez da CLI. A maioria das equipes começa com a CLI porque ela exige quase nenhuma configuração.
O que significa teste baseado em propriedades
A maioria dos testes de API é baseada em exemplos. Você escreve uma requisição, você faz uma asserção sobre uma resposta específica, e o teste passa ou falha naquele único caso. Isso é útil, mas você só pega os bugs para os quais pensou em escrever um teste.
O teste baseado em propriedades inverte a abordagem. Em vez de um exemplo fixo, você descreve uma propriedade que deve sempre ser verdadeira, então deixa a ferramenta gerar centenas de entradas para tentar quebrá-la. Para o Schemathesis, a propriedade é, grosso modo: "nenhuma requisição válida deve derrubar o servidor ou produzir uma resposta que viole o esquema."
O Schemathesis gera entradas a partir das restrições em sua especificação. Se um campo é um inteiro com um mínimo de 1, ele tentará 1, números grandes, valores de limite e os tipos de entradas que enganam a validação ingênua. Quando um teste falha, o Hypothesis reduz a entrada ao menor caso que ainda reproduz o bug, para que você obtenha uma reprodução mínima e legível em vez de um payload aleatório de 4KB.
Isso é diferente do teste de macaco (monkey testing), que lança entradas aleatórias em uma interface para ver o que falha. O teste baseado em propriedades é estruturado. Ele usa o esquema para gerar entradas que são plausíveis e direcionadas, e sabe como deve ser um resultado correto porque a especificação lhe disse.
Instalando e executando o Schemathesis
Schemathesis é um pacote Python, então você precisa de Python 3 e pip. Instale-o da forma usual:
pip install schemathesis
Você também pode executá-lo sem uma instalação permanente usando uvx schemathesis se tiver o uv configurado. Uma vez instalado, o comando básico aponta para um esquema e uma URL base:
st run http://127.0.0.1:8000/openapi.json
Se o seu esquema estiver em disco em vez de atrás de uma URL, passe o caminho do arquivo e diga ao Schemathesis onde está a API ativa:
st run ./openapi.yaml --url http://127.0.0.1:8000
Para uma API autenticada, adicione um cabeçalho:
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer seu-token'
O Schemathesis descobre cada operação na especificação, gera casos para cada uma e imprime um resumo de quais verificações passaram e quais falharam. As falhas vêm com a requisição exata que ele enviou, para que você possa reproduzi-las com curl ou em qualquer cliente de API. Nomes de flags e valores padrão mudam entre as versões principais, então verifique st run --help em relação à sua versão instalada em vez de confiar em um trecho de blog, incluindo este.
O que o Schemathesis detecta
As verificações padrão visam a lacuna entre o que sua especificação promete e o que seu servidor faz. Aqui está o que tende a surgir.
| Problema | Como ele se parece |
|---|---|
| Erros de servidor | Uma requisição aciona um 500 em vez de um 4xx tratado ou uma resposta válida |
| Violações de esquema | O corpo da resposta não corresponde ao esquema que você declarou para aquele código de status |
| Incompatibilidades de código de status | A API retorna um código de status que a especificação nunca documentou |
| Desvio de Content-type | O tipo de conteúdo da resposta não corresponde ao que a especificação anuncia |
| Bugs com estado | Uma operação funciona sozinha, mas falha dentro de um fluxo de trabalho multi-etapas realista |
Esse último vale uma olhada mais atenta. O Schemathesis pode executar testes com estado, onde ele encadeia operações com base em links em sua especificação, por exemplo, criar um recurso, depois buscá-lo e depois excluí-lo. Bugs que só aparecem em sequência, como um recurso que relata o estado errado após uma atualização, são difíceis de encontrar com testes de uma única requisição. A fase com estado impulsiona essas sequências como uma máquina de estados.
Você pode estender o comportamento padrão com hooks. Hooks são funções Python que permitem personalizar a geração de dados, adicionar suas próprias verificações ou filtrar quais operações são testadas. É assim que as equipes adaptam o Schemathesis a APIs com fluxos de autenticação ou restrições não óbvias que a especificação não pode expressar.
Quando usar o Schemathesis
O Schemathesis ganha seu lugar quando você tem uma especificação OpenAPI ou GraphQL razoavelmente precisa e deseja uma cobertura ampla e barata de casos de borda. Ele é forte em encontrar as falhas para as quais você nunca escreveria um teste manual: entradas não tratadas, formatos de erro não documentados e desvio de contrato entre a especificação e a implementação.
É uma boa opção quando:
- Você mantém uma especificação OpenAPI e deseja que ela seja aplicada contra o servidor real.
- Você está preocupado com 500s não tratados e quer uma camada de fuzzing no CI.
- Sua API possui fluxos de trabalho com estado onde a ordem é importante.
- Sua equipe já trabalha em Python e está confortável com
pipepytest.
É uma opção mais fraca quando sua especificação é incompleta ou desatualizada, pois o Schemathesis só pode testar o que o esquema descreve. Lixo entra, lixo sai. Ele também não substituirá seus testes funcionais baseados em exemplos. Saber que um endpoint nunca falha não é o mesmo que saber que ele retorna o valor correto para uma entrada conhecida. Você precisa de ambos.
Schemathesis e Apidog: onde cada um se encaixa
Apidog e Schemathesis resolvem problemas diferentes e funcionam bem lado a lado. Apidog é uma plataforma completa para projetar, depurar, testar, simular e documentar APIs. Schemathesis é um fuzzer focado em propriedades. Ser honesto sobre o limite é importante aqui.
Apidog não faz fuzzing baseado em propriedades. Seu recurso adjacente mais próximo é o teste de macaco (monkey testing), que envia entrada aleatória para expor falhas. Isso é útil, mas não é o mesmo que teste baseado em propriedades orientado por esquema. O Schemathesis gera entradas a partir das restrições de sua especificação e verifica as respostas em relação ao esquema. Portanto, se você precisa de fuzzing baseado em propriedades, use o Schemathesis, não o Apidog.
Onde o Apidog se encaixa é no resto do ciclo de vida em torno dessa passagem de fuzzing.
| Estágio do fluxo de trabalho | Schemathesis | Apidog |
|---|---|---|
| Fuzzing baseado em propriedades a partir de uma especificação | Sim, recurso principal | Não |
| Design visual de API e edição de especificação | Não | Sim |
| Testes funcionais baseados em exemplos | Limitado | Sim, construtor de testes visual |
| Teste de contrato contra uma especificação | Parcial, via verificações de esquema | Sim, fluxo de trabalho dedicado |
| Servidores mock a partir de um esquema | Não | Sim, mock inteligente |
| Executor de testes CI | Sim, st run |
Sim, apidog run |
| Documentos gerados automaticamente | Não | Sim |
Um emparelhamento prático seria assim: você projeta e mantém a especificação no Apidog, gera casos de teste funcionais e um servidor mock a partir dela, e os executa no CI com apidog run. Em seguida, você adiciona uma passagem de Schemathesis que faz fuzzing da mesma especificação para falhas de casos de borda e violações de contrato. As duas camadas detectam diferentes classes de bugs. O Apidog confirma que a API faz a coisa certa para casos conhecidos; o Schemathesis caça os casos desconhecidos que a quebram.
Se seu objetivo é transformar uma especificação em um conjunto funcional executável em vez de uma execução de fuzzing, o Apidog pode gerar coleções de testes de API a partir de suas especificações OpenAPI diretamente, e você pode baixar o Apidog para experimentar esse fluxo.
Perguntas frequentes
O Schemathesis é gratuito?
Sim. O Schemathesis é de código aberto sob a licença MIT, e a CLI é gratuita para instalar e executar via pip install schemathesis. Há também uma oferta comercial hospedada para equipes que desejam uma experiência gerenciada, mas a ferramenta principal que você executa localmente e no CI não custa nada.
Qual é a diferença entre schemathesis run e st run?
São o mesmo comando. st é um apelido curto para schemathesis, então st run e schemathesis run fazem exatamente a mesma coisa. Use o que preferir. Ambos aceitam um caminho ou URL de esquema, além de opções como --url e --header.
O Schemathesis pode substituir meus testes de API funcionais?
Não, e não é para isso que ele serve. O Schemathesis verifica se sua API não falha e se as respostas correspondem ao esquema. Ele não verifica a lógica de negócios, como se o cálculo de um desconto está correto. Você ainda precisa de testes funcionais baseados em exemplos e de contrato para isso, que você pode construir e executar no Apidog. Trate o Schemathesis como uma camada adicional de fuzzing, não como um substituto.
O Schemathesis funciona com GraphQL?
Sim. O Schemathesis suporta esquemas OpenAPI e GraphQL. Para GraphQL, ele gera consultas a partir das definições de tipo do esquema e verifica as respostas da mesma forma que faz para APIs REST definidas em OpenAPI.
Conclusão
O Schemathesis é uma ferramenta afiada para um trabalho: pegar sua especificação OpenAPI ou GraphQL e testar sua API ativa contra ela com geração baseada em propriedades. Ele encontra as falhas e violações de contrato que os testes baseados em exemplos perdem, e custa quase nada para adicionar ao CI. O que ele não faz é projetar, simular, documentar ou verificar a lógica de negócios.
É aí que o Apidog o complementa. Projete a especificação, gere testes funcionais e mocks, execute-os no CI com apidog run e documente o resultado, tudo em um só lugar, depois adicione o Schemathesis para fuzzing. Baixe o Apidog para construir o lado de design e funcional desse fluxo de trabalho, e deixe o Schemathesis cuidar da caça a casos de borda.