Como Adicionar Ramificação If/Else e Controle de Fluxo em Cenários de Teste de API no Apidog

A maioria dos testes de API segue uma linha reta. Chama o login, chama o checkout, chama o endpoint de recibo, faz as verificações ao longo do caminho. Isso funciona até que um passo possa falhar de uma forma que o próximo passo dependa. Se o login retornar um 401, executar a requisição de checkout é inútil. Pior, esconde a falha real atrás de uma segunda falha enganosa. O que você quer é um teste que leia a resposta do login, decida se deve continuar e relate a verdade sobre onde as coisas falharam.

Essa decisão é lógica condicional, e você a constrói com controle de fluxo. Este guia mostra como adicionar ramificações if/else a um cenário de teste de API no Apidog para que uma execução possa se ramificar com base em uma resposta anterior. Você construirá um cenário real: fazer login, verificar o código de status e prosseguir para o checkout somente quando o login realmente funcionar. Se você é novo em cenários do Apidog, o passo a passo sobre como escrever um cenário de teste com o Apidog aborda os fundamentos lineares sobre os quais este artigo se baseia. Para uma definição do próprio padrão de ramificação, o guia do MDN sobre declarações condicionais é uma boa introdução. Você pode baixar o Apidog e acompanhar gratuitamente.

botão

O que é controle de fluxo e o que não é

No Apidog, os testes automatizados ficam no módulo Testes. A unidade em que você trabalha é um Cenário de Teste, que a documentação descreve como análogo a uma Coleção no Postman. Dentro de um cenário, você organiza os Passos de Teste: cada passo é uma requisição individual ou um elemento de controle de fluxo como uma ramificação, um loop ou um atraso.

Controle de fluxo é o conjunto de elementos de controle de fluxo. Ele permite que um cenário faça mais do que apenas percorrer requisições em ordem. A documentação do Apidog sobre controle de fluxo e ramificação condicional é a referência por trás de cada termo usado aqui. O foco deste artigo é a Ramificação Condicional, que é o nome do Apidog para if/else. Uma ramificação lê um valor que você fornece, testa esse valor contra uma condição e executa um conjunto de passos quando a condição é verdadeira e outro conjunto quando não é.

Uma clarificação inicial, porque os dois são frequentemente confundidos. Ramificação não é looping. Uma ramificação decide uma vez se um bloco de passos é executado. Um loop executa um bloco várias vezes. O Apidog possui recursos separados para iteração, chamados For Loops e ForEach Loops, e eles pertencem a um problema diferente: repetir a mesma requisição em um determinado intervalo ou sobre os itens de um array. Se você precisa percorrer um array de IDs de pedidos, isso é um loop ForEach, abordado no tutorial de loop ForEach, e não uma ramificação. Este guia se mantém no if/else.

A documentação do Apidog não lista nenhuma restrição gratuita versus paga para controle de fluxo, ramificação condicional, loops ou passagem de dados entre passos. Também não há distinção de nuvem versus auto-hospedado para esses recursos. Se você pode construir um cenário, você pode adicionar uma ramificação a ele.

Aqui está o objetivo. Um usuário faz login. Se o endpoint de login retornar 200, o cenário prossegue para criar um checkout. Se retornar qualquer outra coisa, o cenário para e reporta a falha, em vez de fingir que o checkout foi executado.

Passo 1: crie o cenário de teste

Abra o Apidog e vá para o módulo Testes. Clique no + ao lado da barra de pesquisa para criar um novo Cenário de Teste, escolha o diretório onde ele deve residir e defina uma prioridade para finalizar a criação. Agora você tem um cenário vazio pronto para os passos.

Adicione seu primeiro Passo de Teste. O Apidog oferece algumas maneiras de adicionar uma requisição: importe de uma especificação de endpoint existente, importe de um caso de endpoint salvo, adicione uma requisição personalizada diretamente ou adicione uma a partir de uma string cURL. Para começar rapidamente, adicione uma requisição personalizada. Defina-a como POST e aponte-a para o seu endpoint de autenticação com um corpo JSON:

POST https://api.your-store.com/v1/login
Content-Type: application/json

{
  "email": "dana@example.com",
  "password": "correct-horse-battery-staple"
}

Execute este passo uma vez por conta própria para confirmar que ele retorna o que você espera. Um bom login retorna um 200 e um token no corpo, algo como:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "usr_10482"
}

Passo 3: entre no modo de orquestração

Clique em qualquer passo para entrar no modo de orquestração. O painel esquerdo mostra o fluxo geral do cenário; o painel direito mostra os detalhes do passo que você selecionou. Essa visualização dividida é onde você organiza a ramificação. Se você precisar reordenar os passos, arraste o ícone ≡ em um passo para movê-lo.

Passo 4: adicione a ramificação condicional

Clique no botão Adicionar Passo. Esta é a principal maneira de inserir qualquer elemento de controle de fluxo. No menu, escolha Ramificação Condicional. Isso cria uma declaração If, uma ramificação vazia esperando por uma condição e alguns passos para executar.

Agora construa a condição. Você precisa alimentar o código de status da resposta de login na ramificação. O Apidog constrói condições a partir de um conjunto fixo de operadores de julgamento. A lista completa é: Igual a, Diferente de, Existe, Não existe, Menor que, Menor ou igual a, Maior que, Maior ou igual a, Corresponde a Regex, Contém, Não contém, Está vazio, Não está vazio, Na lista e Não na lista.

Para esta ramificação, você quer que o código de status do login seja igual a 200. Então a condição lê: o status da resposta de login Igual a 200.

Passo 5: referencie a resposta anterior na condição

Para obter o resultado do login no campo da condição, você tem dois métodos.

O primeiro método não precisa de configuração. Clique no campo de valor da condição e clique no ícone da varinha mágica, depois selecione Recuperar dados do passo anterior. O Apidog permite que você aponte diretamente para o passo de login anterior e extraia um valor de sua resposta. Por baixo dos panos, isso usa uma referência de pré-passo com a sintaxe {{$.<id do passo>.response.body.<caminho do campo>}}. Se você quisesse o token do corpo do login em vez do status, por exemplo, você referenciaria {{$.1.response.body.token}}, onde 1 é o ID do passo de login.

Duas coisas a saber sobre Recuperar dados do passo anterior. Ele funciona apenas no módulo Testes, não no módulo APIs. E ele se resolve apenas quando você executa o cenário completo, não quando você executa um único passo isoladamente. Se uma referência de pré-passo parecer vazia durante uma execução individual, isso é esperado; execute o cenário completo e ela será preenchida.

O segundo método usa uma variável nomeada e funciona tanto nos módulos Testes quanto APIs. Na requisição de login, abra seus pós-processadores e adicione uma ação Extrair Variável. Extraia o campo que lhe interessa com uma expressão JSONPath, digamos $.token, e o Apidog o armazenará sob um nome. Você então o referencia em qualquer lugar mais tarde como {{token}}. Esta é a abordagem mais portátil quando você deseja o mesmo valor disponível em vários módulos ou em várias ramificações. A mecânica mais aprofundada de mover valores entre passos é abordada no guia sobre como passar dados entre passos de teste.

Para a ramificação do código de status, Recuperar dados do passo anterior no status do passo de login é o caminho mais curto.

Passo 6: adicione a ramificação else

Passe o mouse sobre o bloco If e clique em + Else. Isso lhe dá o caminho alternativo que é executado quando a condição é falsa, significando que o login não retornou 200.

Agora preencha ambos os lados:

Dentro do bloco If, adicione a requisição de checkout como um Passo de Teste. Este é o caminho feliz. Ele é executado apenas quando o login retorna 200. Se o checkout precisar do token de login, referencie-o aqui com {{token}} (se você o extraiu) ou com uma referência de pré-passo para o corpo do login. Uma chamada de checkout real geralmente carrega um token de portador no cabeçalho Authorization, o mesmo padrão que a documentação da API Stripe usa para requisições autenticadas.
Dentro do bloco Else, adicione um passo que torne a falha evidente. Uma escolha comum é uma requisição para um endpoint de log ou notificação, ou uma requisição personalizada com uma asserção que sempre falha para que o relatório do cenário sinalize claramente esta execução.

Seu cenário agora lê como lógica simples: se o login for igual a 200, execute o checkout; caso contrário, reporte e pare.

Passo 7: salvar

Clique em Salvar Tudo para persistir o cenário. Mudanças não salvas mostram um indicador de ponto, então se você vir esse ponto, você ainda tem trabalho a fazer. Execute o cenário completo e observe a ramificação se resolver. Aponte o login para credenciais válidas e o bloco If será acionado. Aponte-o para credenciais inválidas e o bloco Else será acionado em seu lugar.

Variações e controle de fluxo avançado

Uma vez que a ramificação básica funciona, os mesmos blocos de construção cobrem muito terreno.

Ramifique em um campo do corpo, não apenas no status. Códigos de status são o caso comum, mas as condições leem qualquer valor que você possa referenciar. Suponha que seu login retorne 200 mesmo para uma conta bloqueada, com o estado real em um campo status. Recupere {{$.1.response.body.status}} e use o operador Igual a contra "active", ou use Contém contra uma string de mensagem. A lista de operadores também oferece verificações de intervalo: Maior que em um saldo retornado, Na Lista para testar se um papel retornado é um dos vários valores permitidos.

Combine ramificação com loops. Ramificação e iteração se complementam. Dentro de um loop ForEach sobre um array de IDs de produtos, um passo de Ramificação Condicional pode pular produtos que estão fora de estoque e processar o restante. A referência de índice do loop {{$.<id do passo do loop>.index}} começa em 0, e um elemento ForEach é {{$.<id do passo do loop>.element.<caminho do campo>}}. Loops são um tópico à parte; o tutorial de loop ForEach os aborda adequadamente.

Pare um loop cedo com Break If. Quando você está iterando, o elemento Condição Break If encerra o loop assim que uma condição é atendida. Você pode arrastá-lo para reposicioná-lo e adicioná-lo mais de uma vez em um loop.

Lide com erros com On Error. Loops carregam um elemento On Error fixado no início do loop, que você não pode mover. Suas opções decidem o que acontece quando uma requisição dentro do loop falha: Ignorar continua com a próxima requisição, Continuar pula o restante das requisições do ciclo atual, Interromper execução para o loop e prossegue após ele, e Finalizar execução interrompe o cenário inteiro.

Adicione uma Espera entre os passos. Às vezes, um serviço downstream precisa de um tempo antes de refletir uma gravação. O elemento Esperar adiciona um atraso medido em milissegundos, útil entre uma chamada de criação e a leitura que a verifica.

Valores de referência dentro de scripts. Se uma ramificação precisar de lógica muito complexa para a lista de operadores, um script de pré-processamento ou pós-processamento pode calculá-la. Dentro de um script, você não pode usar a sintaxe {{variável}} diretamente. Use pm.variables.get("$.2.response.body.token") em vez disso, combinando o ID do passo e o caminho do campo. Para o padrão mais amplo de encadeamento de requisições, onde uma alimenta a próxima, consulte o guia sobre encadeamento de requisições e o artigo mais aprofundado sobre orquestração de testes de API e passagem de dados.

Uma nota sobre auto-referência: um cenário não pode referenciar o cenário de teste original em si. Essa proteção evita loops infinitos acidentais ao aninhar cenários.

Automatize o fluxo de trabalho com o Apidog CLI

O cenário que você acabou de construir não precisa ser executado apenas dentro do aplicativo. O Apidog oferece um executor de linha de comando que executa cenários salvos sem interface gráfica (headless), o que é exatamente o que você deseja em CI. Instale-o e faça login:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Em seguida, execute seu cenário de ramificação por ID, apontando-o para um ambiente e escolhendo um reportador:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

Aqui, -t é o ID do cenário de teste, -e é o ID do ambiente e -r é o reportador. Use cli para saída no console, ou html e junit para artefatos que seu pipeline pode publicar; separe-os por vírgula como -r html,cli para emitir vários de uma vez. A ramificação se resolve da mesma forma que no aplicativo: o executor lê a resposta do login, segue o caminho If ou Else, e o código de saída reflete o resultado, de modo que um login falho reprova a compilação. A configuração completa está no guia de instalação do Apidog CLI, e a integração em um pipeline é abordada no guia do Apidog CLI GitHub Actions. Se você preferir executar o mesmo cenário em um temporizador em vez de em cada commit, veja como agendar testes de API no Apidog.

FAQ

Qual a diferença entre Ramificação Condicional e um loop no Apidog?

A Ramificação Condicional decide uma vez se um bloco de passos é executado, com base em uma condição. Um loop executa um bloco repetidamente. Use uma ramificação quando tiver uma decisão de "ou isso ou aquilo", como prosseguir para o checkout apenas se o login foi bem-sucedido. Use um loop For ou ForEach quando precisar repetir uma requisição em uma contagem ou em um array. O tutorial de loop ForEach aborda a iteração completamente.

Por que minha referência de Recuperar dados do passo anterior está voltando vazia?

Duas causas comuns. Primeiro, Recuperar dados do passo anterior funciona apenas no módulo Testes, não no módulo APIs. Segundo, ele se resolve apenas quando você executa o cenário de teste inteiro. Se você executar um único passo isoladamente, a referência ainda não tem para onde apontar. Execute o cenário completo e o valor será preenchido.

Posso ramificar em um campo dentro do corpo da resposta, e não apenas no código de status?

Sim. Referencie o campo com uma expressão de pré-passo como {{$.1.response.body.status}} ou extraia-o para uma variável nomeada, depois escolha um operador como Igual a, Contém ou Na Lista. Qualquer valor que você possa referenciar pode impulsionar uma condição. A movimentação desses valores é abordada em como passar dados entre passos de teste.

Como uso uma variável dentro de um script em vez de um construtor de condição?

Scripts não aceitam a sintaxe {{variable}}. Use pm.variables.get("$.2.response.body.token") em um script de pré-processamento ou pós-processamento, combinando o ID do passo e o caminho do campo que você deseja.

A ramificação custa extra ou exige a versão auto-hospedada?

A documentação do Apidog não lista nenhuma restrição de plano para controle de fluxo, ramificação condicional, loops ou passagem de dados, e nenhuma distinção de nuvem versus auto-hospedado para esses recursos. Se você pode construir um cenário, você pode adicionar ramificações a ele.

Conclusão

Um teste linear diz que algo quebrou. Um teste com ramificação diz onde, e para de desperdiçar passos em um caminho que não pode mais ter sucesso. Adicione um passo de Ramificação Condicional, alimente-o com uma resposta anterior usando Recuperar dados do passo anterior ou uma variável extraída, conecte o If e o + Else, e seu cenário agora toma decisões da mesma forma que sua API real. Quando funciona no aplicativo, um comando apidog run leva a mesma lógica para o CI. Experimente o Apidog gratuitamente, sem necessidade de cartão de crédito, e transforme seus testes lineares em cenários que pensam.