Uma requisição de API que retorna uma resposta não é um teste aprovado. É apenas uma resposta. O teste só existe quando algo verifica se a resposta está correta. Essa verificação é uma asserção, e a qualidade das suas asserções decide se o seu conjunto de testes detecta bugs reais ou apenas confirma que o servidor está funcionando.
Este guia explica o que são as asserções de API, os tipos que valem a pena escrever, onde as equipes erram e como construir asserções visualmente no Apidog sem usar scripts.
O que é uma asserção de API
Uma asserção é uma declaração sobre uma resposta que deve ser verdadeira para que o teste seja aprovado. Você envia uma requisição, a API responde, e a asserção compara uma parte dessa resposta com um valor esperado. Se eles corresponderem, passa. Se não, falha.
Sem asserções, um teste automatizado prova apenas que o endpoint é acessível. Com elas, prova que o endpoint está correto. A diferença entre esses dois é onde a maioria dos incidentes de produção reside: a API estava no ar, retornou um 200, e o corpo estava errado.
Uma asserção útil é específica e independente. Específica, para que uma falha aponte para uma única coisa. Independente, para que não dependa silenciosamente de outra asserção ter sido aprovada primeiro. Uma única etapa de teste geralmente contém várias asserções, cada uma verificando uma faceta diferente da mesma resposta.
A asserção de código de status e por que ela não é suficiente
A asserção mais comum verifica o código de status HTTP: espera 200 para uma leitura bem-sucedida, 201 para um recurso criado, 400 para entrada inválida, 401 para autenticação ausente. Isso é necessário. Acertar os códigos de status é uma disciplina em si; quais códigos de status HTTP as APIs REST devem usar vale a pena ler se sua API for inconsistente aqui.
Mas uma asserção de código de status sozinha é fraca. Uma API pode retornar 200 OK com um corpo vazio, um valor obsoleto, um nulo onde um objeto deveria estar, ou uma mensagem de erro disfarçada de sucesso. O status diz que a requisição foi tratada. Não diz nada sobre se os dados estão corretos.
Trate a asserção de status como a primeira linha de uma etapa de teste, nunca a única linha.
Os tipos de asserção que valem a pena escrever
Asserções de conteúdo do corpo. Verifique os valores reais na resposta. O campo id existe e não está vazio. O email corresponde ao que você enviou. O total é igual à soma dos itens. Isso detecta bugs de lógica que os códigos de status ignoram.
Asserções de esquema. Valide a estrutura da resposta em relação a um Schema JSON ou uma definição OpenAPI: campos obrigatórios estão presentes, tipos estão corretos, nenhum campo inesperado apareceu. As asserções de esquema detectam o desvio de contrato, onde o backend muda silenciosamente um campo de string para objeto e quebra todos os clientes. Isso se sobrepõe ao teste de contrato de API, que formaliza a ideia entre produtor e consumidor.
Asserções de cabeçalho. Confirme se o Content-Type é application/json, se os cabeçalhos de cache estão configurados conforme o esperado, se os cabeçalhos CORS estão presentes e se os cabeçalhos de segurança como Strict-Transport-Security estão lá.
Asserções de tempo de resposta. Defina um orçamento de latência, digamos 800 ms, e falhe o teste quando a resposta for mais lenta. Regressões de desempenho são invisíveis para todos os outros tipos de asserção, então esta é a única que as detecta em um conjunto funcional.
Asserções de forma de erro. Para casos negativos, afirme o corpo do erro, não apenas o código 4xx. O campo error é igual a validation_error, o array details nomeia o campo ofensivo e nenhum dado sensível vaza na mensagem.
Asserções de segurança. Confirme se o endpoint rejeita requisições sem token, rejeita tokens expirados, impõe autorização entre usuários e não ecoa payloads de injeção sem escape.
Uma etapa de teste que afirma status, dois ou três campos do corpo, o esquema e um orçamento de tempo de resposta está fazendo um trabalho real. Uma etapa que afirma apenas o status é decorativa.
Onde a lógica de asserção falha
Excesso de asserções em dados voláteis. Afirmar um timestamp created_at exato ou um UUID gerado faz o teste falhar em cada execução sem motivo. Afirme que o campo existe e tem o tipo correto, não seu valor exato.
Falta de asserções no caminho feliz. O teste do caminho feliz é o que provavelmente afirma apenas o código de status. É também o que os usuários mais acessam. Dê a ele as asserções mais completas, não as mínimas.
Asserções dependentes de ordem. Se a asserção B só faz sentido quando a asserção A foi aprovada, mas ambas são executadas cegamente, uma falha em A produz uma segunda falha confusa em B. Estruture as etapas para que as dependências sejam explícitas.
Uma asserção fazendo dois trabalhos. “A resposta está correta” não é uma asserção. Divida-a: status é 200, token existe, expires_in é igual a 3600. Três verificações, três mensagens de falha claras.
Ignorando casos negativos. As equipes fazem muitas asserções para o sucesso e poucas para a falha. Um caso negativo sem asserção de corpo apenas prova que a API disse “não”, não que ela disse não corretamente.
Construindo asserções no Apidog
No Apidog, as asserções fazem parte do construtor visual de testes, então você as define clicando em vez de usar scripts.
Para qualquer requisição em um cenário de teste, abra o painel de asserções e adicione verificações:
- Asserção de status. Selecione “response status” e defina-o como igual a
200. - Asserções de campo do corpo. Use uma expressão JSONPath como
$.tokene afirme que ela existe e é uma string não vazia; afirme que$.expires_iné igual a3600. O Apidog lê a estrutura da resposta, então você escolhe os campos em vez de digitar caminhos às cegas. - Asserção de esquema. Valide a resposta em relação ao esquema definido do endpoint. Como o Apidog mantém o design da API e os testes em um único espaço de trabalho, o esquema que sua asserção usa é o mesmo esquema que sua documentação publica; não há uma segunda cópia para desviar.
- Asserção de tempo de resposta. Adicione uma verificação de que o tempo de resposta está abaixo do seu orçamento.
- Script personalizado, somente quando necessário. Para lógicas que as verificações visuais não conseguem expressar, use um pós-processador JavaScript. A maioria das asserções nunca precisa disso.
Agrupe as asserções em um cenário e o Apidog as executa juntas. Para uma cobertura que escala, anexe um arquivo de dados para que um conjunto de asserções seja executado contra cada linha de entrada de teste orientada a dados. Quando o cenário é executado, o relatório gerado mostra exatamente qual asserção falhou, em qual requisição, com os valores esperados e reais lado a lado.
O mesmo cenário é executado inalterado no CI, então cada commit verifica novamente cada asserção; a automação de testes de API em CI/CD cobre essa fiação. Baixe o Apidog para construir um conjunto de asserções contra seu próprio endpoint.
Um conjunto de asserções demonstrativo
Considere GET /users/{id} retornando um objeto de usuário. Um conjunto de asserções sólido para o caminho feliz:
- Status igual a
200 - Cabeçalho
Content-Typecontémapplication/json $.idé igual ao id solicitado$.emailexiste e corresponde a um padrão de e-mail$.roleé um deadmin,member,viewer- Corpo da resposta está em conformidade com o esquema
User - Tempo de resposta está abaixo de 600 ms
E para GET /users/{id} com um id desconhecido:
- Status igual a
404 $.erroré igual anot_found- O corpo da resposta não contém
email,idou outros campos de usuário
Duas requisições, onze asserções, e você verificou o contrato, os dados, os cabeçalhos, o desempenho e o comportamento de erro. É isso que separa um conjunto de testes que protege um lançamento de um que apenas verifica o servidor.
Asserções em um pipeline de CI
As asserções ganham seu valor total quando são executadas automaticamente. Um conjunto de testes que alguém executa manualmente uma vez por semana detecta bugs com uma semana de atraso. O mesmo conjunto integrado ao CI os detecta na pull request.
Quando as asserções são executadas em um pipeline, duas escolhas de design importam. Primeiro, a falha precisa ser inequívoca. Um log de CI que diz "teste falhou" força um desenvolvedor a reproduzir a execução localmente; um log que diz "esperava $.expires_in igual a 3600, obteve 7200 em POST /auth/login" indica imediatamente onde procurar. Asserções fortes e específicas são o que produzem essa falha legível.
Segundo, as asserções precisam ser estáveis entre ambientes. Uma asserção que codifica um ID de usuário de produção falhará no ambiente de staging por um motivo que não tem nada a ver com o código. Mantenha os valores específicos do ambiente em variáveis e afirme a estrutura e o tipo onde o valor exato depende do ambiente. Uma asserção de esquema funciona bem entre ambientes; uma asserção em um ID gerado específico não.
O padrão prático: afirme o status e o esquema em cada endpoint como uma base que é executada em todos os lugares, e então adicione asserções de valor sensíveis ao ambiente. A base detecta o desvio de contrato em qualquer ambiente; as asserções de valor detectam bugs de lógica onde você tem dados estáveis. Execute ambos em cada commit e o conjunto se torna um portão em vez de um relatório.
Perguntas frequentes
Qual a diferença entre uma asserção e um caso de teste? Um caso de teste é a verificação completa: uma requisição mais seu resultado esperado. As asserções são as comparações individuais dentro dele que decidem se passa ou falha. Veja como escrever casos de teste de API.
Quantas asserções uma requisição deve ter? O suficiente para cobrir o status, os campos-chave do corpo, o esquema e um orçamento de latência. Para a maioria dos endpoints, são de quatro a oito. Mais é aceitável se cada uma verificar algo distinto.
Devo afirmar corpos de resposta exatos? Afirme campos estáveis exatamente e campos voláteis por tipo ou presença. Afirmar um corpo completo, incluindo timestamps e IDs gerados, cria testes que falham em cada execução.
Posso verificar o desempenho da API em um teste funcional? Sim. Uma asserção de tempo de resposta detecta regressões de latência durante as execuções funcionais normais, sem a necessidade de um teste de carga separado para a verificação básica do orçamento.
Os casos de teste negativos também devem ter asserções? Absolutamente, e são os casos mais frequentemente deixados em aberto. Um caso negativo com apenas uma verificação de código de status prova que a API disse "não", não que ela disse não corretamente. Afirme o campo de erro, o detalhe do campo ofensivo e a ausência de quaisquer dados sensíveis na mensagem.
Onde scripts de asserção personalizados devem ser usados? Reserve scripts para lógicas que o construtor visual não consegue expressar: comparações entre requisições, valores derivados ou verificações condicionais que dependem de respostas anteriores. A maioria das asserções, status, esquema, campos do corpo e tempo, são mais limpas e revisáveis como verificações visuais.