DEV Community

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

Posted on • Originally published at apidog.com

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 e valida cada resposta. Isso deixa de funcionar quando uma falha em um passo invalida os próximos. Se o login retorna 401, executar o checkout é inútil e pode esconder a causa real atrás de erros secundários. A solução é ler a resposta anterior, decidir se o cenário deve continuar e reportar exatamente onde ocorreu a falha.

Experimente o Apidog hoje

Essa decisão usa lógica condicional e controle de fluxo. Neste guia, você vai configurar uma ramificação if/else em um cenário de teste de API no Apidog: faça login, valide o status da resposta e só execute o checkout se a autenticação for bem-sucedida. Se você ainda não criou cenários no Apidog, consulte o guia sobre como escrever um cenário de teste com o Apidog. Para revisar o conceito de if/else, veja o guia do MDN sobre declarações condicionais.

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

No Apidog, os testes automatizados ficam no módulo Testes. Você trabalha com um Cenário de Teste, semelhante a uma coleção no Postman, composto por Passos de Teste.

Cada passo pode ser:

Interface de controle de fluxo no Apidog

Controle de fluxo permite que o cenário faça mais do que executar requisições em sequência. A documentação do Apidog sobre controle de fluxo e ramificação condicional descreve os elementos disponíveis.

Neste artigo, o foco é a Ramificação Condicional, equivalente a if/else:

  1. ela lê um valor de uma resposta ou variável;
  2. testa esse valor com uma condição;
  3. executa um grupo de passos se a condição for verdadeira;
  4. executa outro grupo se a condição for falsa.

Ramificação não é loop.

Uma ramificação decide uma vez qual caminho executar. Um loop executa o mesmo bloco várias vezes.

Se você precisa percorrer uma lista de IDs de pedidos, use um loop ForEach, não uma ramificação. Consulte o tutorial de loop ForEach para esse caso.

A documentação do Apidog não lista restrições de plano, nem diferenças entre nuvem e auto-hospedado, para controle de fluxo, ramificações, loops ou passagem de dados entre passos.

Construa um cenário que decide com base no login

Objetivo do fluxo:

Login
  ├─ status 200 → Checkout
  └─ qualquer outro status → Reportar falha e encerrar
Enter fullscreen mode Exit fullscreen mode

Assim, um checkout nunca será executado se o login falhar.

Passo 1: crie um cenário de teste

  1. Abra o Apidog e entre no módulo Testes.
  2. Clique em + ao lado da barra de pesquisa.
  3. Crie um novo Cenário de Teste.
  4. Escolha o diretório e defina a prioridade.
  5. Finalize a criação.

Agora você tem um cenário vazio para montar o fluxo.

Passo 2: adicione a requisição de login

Adicione o primeiro Passo de Teste como uma requisição personalizada.

Configure uma requisição POST para o endpoint de autenticação:

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

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

Antes de criar a ramificação, execute esse passo isoladamente e confirme a resposta esperada. Um login bem-sucedido pode retornar:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "usr_10482"
}
Enter fullscreen mode Exit fullscreen mode

Valide pelo menos:

  • o status HTTP, como 200;
  • o formato do corpo;
  • a presença do token, caso o checkout precise dele.

Passo 3: entre no modo de orquestração

Clique em qualquer passo para abrir o modo de orquestração.

Nessa visualização:

  • o painel esquerdo mostra o fluxo do cenário;
  • o painel direito exibe os detalhes do passo selecionado;
  • o ícone ≡ permite reordenar passos por arrastar e soltar.

É nesse modo que você adiciona e organiza ramificações.

Passo 4: adicione uma Ramificação Condicional

  1. Clique em Adicionar Passo.
  2. Selecione Ramificação Condicional.
  3. Configure a condição para avaliar a resposta do login.

O Apidog oferece operadores como:

  • 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
  • Não na lista

Para este cenário, a regra deve ser:

status da resposta de login Igual a 200
Enter fullscreen mode Exit fullscreen mode

Passo 5: use a resposta do passo anterior

Para alimentar a condição com dados do login, use uma destas abordagens.

Opção A: Recuperar dados do passo anterior

Essa é a forma mais rápida quando o valor será usado apenas no cenário de teste.

  1. Clique no campo de valor da condição.
  2. Clique no ícone de varinha mágica.
  3. Selecione Recuperar dados do passo anterior.
  4. Escolha o passo de login e o status da resposta.
  5. Compare o valor com 200.

Por baixo dos panos, o Apidog usa referências de pré-passo com esta estrutura:

{{$.<id do passo>.response.body.<caminho do campo>}}
Enter fullscreen mode Exit fullscreen mode

Por exemplo, para acessar um token retornado pelo passo 1:

{{$.1.response.body.token}}
Enter fullscreen mode Exit fullscreen mode

Recuperar dados do passo anterior no Apidog

Observe duas limitações importantes:

  • Recuperar dados do passo anterior funciona no módulo Testes, não no módulo APIs.
  • A referência é resolvida ao executar o cenário completo. Ao executar apenas um passo isolado, ela pode aparecer vazia.

Opção B: extraia uma variável nomeada

Use essa alternativa quando você precisar reutilizar um valor em vários módulos, passos ou ramificações.

Na requisição de login:

  1. Abra os pós-processadores.
  2. Adicione a ação Extrair Variável.
  3. Use uma expressão JSONPath, por exemplo: 
$.token
Enter fullscreen mode Exit fullscreen mode
  1. Salve o resultado em uma variável como token.

Depois, use a variável em passos posteriores:

{{token}}
Enter fullscreen mode Exit fullscreen mode

Para aprofundar esse fluxo, consulte o guia sobre como passar dados entre passos de teste.

Para validar somente o status HTTP do login, recuperar o dado do passo anterior é o caminho mais direto.

Passo 6: configure o caminho Else

Passe o mouse sobre o bloco If e clique em + Else.

Agora preencha os dois caminhos.

Caminho If: login bem-sucedido

Dentro do bloco If, adicione a requisição de checkout.

Se o checkout exigir o token retornado pelo login, inclua-o no cabeçalho:

Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

Ou use uma referência de pré-passo para o token:

{{$.1.response.body.token}}
Enter fullscreen mode Exit fullscreen mode

O uso de token de portador no cabeçalho Authorization segue o padrão comum de APIs autenticadas, como mostrado na documentação da API Stripe.

Caminho Else: login falhou

Dentro do bloco Else, adicione um passo que deixe a falha explícita. Você pode:

  • chamar um endpoint de log;
  • enviar uma notificação;
  • adicionar uma requisição personalizada com uma asserção que falhe intencionalmente.

O objetivo é fazer o relatório mostrar claramente que o cenário parou porque o login não retornou 200.

O resultado final é:

Se login.status == 200:
  executar checkout
Senão:
  reportar falha
Enter fullscreen mode Exit fullscreen mode

Passo 7: salve e execute o cenário

Clique em Salvar Tudo.

Se houver alterações pendentes, o Apidog mostrará um indicador de ponto. Em seguida, execute o cenário inteiro:

  • use credenciais válidas para testar o caminho If;
  • use credenciais inválidas para testar o caminho Else.

Variações e controle de fluxo avançado

Depois de configurar a ramificação básica, você pode aplicar a mesma estrutura a outros casos.

Ramifique usando um campo do corpo

Você não precisa limitar a condição ao status HTTP.

Imagine que o endpoint retorne 200 mesmo quando a conta está bloqueada:

{
  "status": "blocked"
}
Enter fullscreen mode Exit fullscreen mode

Nesse caso, avalie o campo retornado:

{{$.1.response.body.status}}
Enter fullscreen mode Exit fullscreen mode

E configure uma condição como:

Igual a "active"
Enter fullscreen mode Exit fullscreen mode

Outros exemplos:

  • Contém para verificar uma mensagem;
  • Maior que para validar saldo ou quantidade;
  • Na lista para permitir apenas determinados papéis de usuário.

Combine ramificações com loops

Ramificações e loops resolvem problemas diferentes, mas funcionam bem juntos.

Por exemplo, em um ForEach que percorre IDs de produtos, você pode usar uma Ramificação Condicional para ignorar itens sem estoque e processar apenas os disponíveis.

Referências úteis dentro de um loop:

{{$.<id do passo do loop>.index}}
Enter fullscreen mode Exit fullscreen mode

O índice começa em 0.

Para acessar o elemento atual:

{{$.<id do passo do loop>.element.<caminho do campo>}}
Enter fullscreen mode Exit fullscreen mode

Veja o tutorial de loop ForEach para detalhes.

Exemplo de controle de fluxo com loop

Encerre loops com Break If

Em fluxos iterativos, use Condição Break If para encerrar o loop assim que uma condição for atendida.

Você pode:

  • arrastar o elemento para mudar sua posição;
  • adicionar mais de uma condição Break If no mesmo loop.

Trate falhas com On Error

Loops incluem um elemento On Error fixado no início do fluxo. Ele define o que fazer quando uma requisição dentro do loop falha:

  • Ignorar: continua para a próxima requisição;
  • Continuar: pula o restante das requisições da iteração atual;
  • Interromper execução: encerra o loop e segue para os passos posteriores;
  • Finalizar execução: interrompe todo o cenário.

Adicione espera entre passos

Use o elemento Esperar quando um serviço downstream precisa de tempo para refletir uma alteração.

O atraso é definido em milissegundos e é útil, por exemplo, entre:

Criar recurso → Esperar → Consultar recurso
Enter fullscreen mode Exit fullscreen mode

Use valores em scripts

Quando a lógica for mais complexa do que os operadores do construtor de condições permitem, calcule o resultado em um script de pré-processamento ou pós-processamento.

Em scripts, a sintaxe {{variável}} não funciona diretamente. Use:

pm.variables.get("$.2.response.body.token")
Enter fullscreen mode Exit fullscreen mode

A referência combina o ID do passo com o caminho do campo.

Para cenários de encadeamento, consulte:

Um cenário não pode referenciar a si mesmo como cenário de teste original. Essa proteção evita loops infinitos acidentais ao aninhar cenários.

Automatize o cenário com o Apidog CLI

Depois de validar o fluxo na interface, execute o mesmo cenário no CI usando o Apidog CLI.

Instale a CLI e autentique-se:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Em seguida, execute o cenário por ID:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

Parâmetros:

Opção Descrição
-t ID do cenário de teste
-e ID do ambiente
-r Formato do relatório

Use cli para saída no console. Para gerar artefatos de pipeline, use html ou junit:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t <scenario_id> \
  -e <env_id> \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

A ramificação é resolvida da mesma forma que na interface:

  1. a CLI executa o login;
  2. lê a resposta;
  3. segue o caminho If ou Else;
  4. retorna um código de saída compatível com CI.

Consulte:

FAQ

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

A Ramificação Condicional toma uma decisão única: executar ou não um bloco de passos.

Um loop repete um bloco várias vezes.

Use ramificação para decisões como:

Executar checkout apenas se o login funcionar
Enter fullscreen mode Exit fullscreen mode

Use For ou ForEach para repetir requisições por contagem ou para cada item de um array. Veja o tutorial de loop ForEach.

Por que Recuperar dados do passo anterior retorna vazio?

As causas mais comuns são:

  1. o recurso funciona somente no módulo Testes, não no módulo APIs;
  2. a referência é resolvida ao executar o cenário completo, não um único passo isolado.

Execute o cenário inteiro para preencher o valor.

Posso ramificar por um campo do corpo da resposta?

Sim.

Use uma referência como:

{{$.1.response.body.status}}
Enter fullscreen mode Exit fullscreen mode

Ou extraia o valor para uma variável nomeada. Depois, aplique operadores como Igual a, Contém ou Na lista.

Veja como passar dados entre passos de teste.

Como uso uma variável dentro de um script?

Scripts não aceitam {{variable}} diretamente.

Use:

pm.variables.get("$.2.response.body.token")
Enter fullscreen mode Exit fullscreen mode

Ajuste o ID do passo e o caminho do campo para o valor que deseja acessar.

A Ramificação Condicional exige plano pago ou versão auto-hospedada?

A documentação do Apidog não lista restrições de plano para controle de fluxo, ramificações condicionais, loops ou passagem de dados. Também não indica distinção entre nuvem e auto-hospedado para esses recursos.

Conclusão

Um teste linear informa que algo falhou. Um teste com ramificação mostra onde falhou e evita executar passos que já não podem ter sucesso.

Para implementar esse padrão:

  1. adicione uma Ramificação Condicional;
  2. use a resposta anterior ou uma variável extraída como entrada;
  3. configure o bloco If para o caminho de sucesso;
  4. configure + Else para registrar e encerrar falhas;
  5. execute o mesmo cenário no CI com apidog run.

Experimente o Apidog gratuitamente, sem necessidade de cartão de crédito, e transforme testes lineares em cenários que tomam decisões.

Top comments (0)