Pular para o conteúdo
LabS Atlas
AI For Devs
Entrar

Geração de Testes de API a partir do Swagger

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

Geração de testes de API a partir do Swagger é a técnica em que código comum filtra da especificação só o essencial de um endpoint e um modelo de linguagem gera, executa e documenta testes com esse texto.

A especificação Swagger já descreve o que um teste precisa saber, mas o JSON bruto é verboso e enviá-lo inteiro ao modelo encarece cada chamada. A técnica divide o trabalho: o determinístico fica com o código, e só o que exige interpretação vai para o modelo, o que reduz o Custo de Tokens e a margem para erro.

Filtrar o Swagger com código, sem IA

A etapa de pré-processamento recebe a URL da documentação Swagger e o endpoint a testar. Ela lê o objeto JSON da especificação, localiza o endpoint e extrai o tipo de requisição (GET, POST e afins), a URL base, o esquema do corpo com o tipo de cada campo (string, inteiro, double), os parâmetros, quando existem, e os exemplos de requisição, quando a documentação os traz. A saída é um texto curto e organizado, pronto para entrar no prompt.

A extração usa regex e manipulação de strings, num script de cerca de 274 linhas cujo único objetivo é economizar tokens e organizar o texto. A comparação justifica não usar IA aqui: o Swagger bruto de um projeto pequeno consumiu sozinho algo entre 1.200 e 1.400 tokens de entrada, enquanto as chamadas com o texto filtrado ficaram em poucas centenas.

O nome adequado para essa etapa é limpeza (cleaning) dos dados; sanitização remete à destruição definitiva de dados.

Do pedido em linguagem natural ao relatório em PDF

Com o texto filtrado, o usuário escreve o pedido em linguagem natural, por exemplo quatro testes para o endpoint de registro, um de sucesso e três de erro. O modelo devolve um JSON com o tipo de requisição e a lista de tarefas de teste. O fluxo percorre cada tarefa, dispara a requisição real contra a API e registra o resultado, mantendo entre as chamadas só um resumo curto do que já foi feito, em vez do contexto inteiro.

Numa execução, a etapa inicial consumiu 415 tokens de entrada e 70 de saída, e a montagem das tarefas, 303 de entrada e 78 de saída, valores exibidos por um log de consumo configurado no projeto. Os testes gerados cobriram cadastro válido, e-mail inválido, e-mail vazio e senha vazia, e o relatório ficou pronto em cerca de meio minuto.

O relatório é pedido em Markdown. Texto puro fica sem formatação ao virar PDF, e pedir HTML direto ao modelo gastaria mais tokens de saída; o Markdown é convertido em HTML e depois em PDF com uma biblioteca Java.

Um bug real exposto pelo teste gerado

O teste de cadastro com e-mail já existente revelou um defeito da própria API: em vez do status 400 esperado para esse conflito, ela respondeu 500, um erro inesperado do servidor. Além de documentar o comportamento esperado, a técnica exercita a API de verdade.

Como manter o modelo no padrão

Três cuidados reduzem a Alucinação e os desvios de formato:

  • Exemplo de entrada completo no prompt de sistema: quanto mais descritivo, menor a chance de o modelo fugir do padrão.
  • Formato de saída rigidamente definido, no espírito da Saída Estruturada de LLMs: com entrada e saída refinadas, o modelo não desviou do formato em nenhum dos testes feitos.
  • Distinção explícita entre operações parecidas: criação e atualização de cadastro podem diferir só no método HTTP, e o prompt precisa dizer como tratar cada método.

Sem dados no pedido, o modelo repete valores genéricos, como João Silva ou John Doe. Especificar a Massa de Dados de Teste no próprio pedido reduz a repetição, mas não garante dados inéditos: um e-mail pedido com letra inicial definida saiu como um valor óbvio que já existia na base.

Agente ou não

Com persona, algum raciocínio e resumo passado adiante, a solução tem traços de agente, mas resolve tudo numa cadeia única. Um agente completo, nos termos dos Elementos de um Agente de IA, teria liberdade para agir, acionando outro agente ou função.