Como Retornar Dados Mock Condicionais no Apidog (Regras Personalizadas e Scripts de Mock)

Smart mock cria uma API falsa em segundos. Ele lê o esquema do endpoint e retorna dados plausíveis: um e-mail com aparência real, um carimbo de data/hora sensato e um nome que não seja xJ8kQ. Para a maioria das tarefas de frontend, isso já é suficiente para desbloquear o desenvolvimento.

Experimente o Apidog hoje

Mas há casos em que dados gerados não bastam. Você pode precisar que:

• POST /login retorne 200 para um usuário conhecido e 401 para os demais;
• GET /orders/{id} retorne pedidos com estados diferentes conforme o ID;
• um endpoint responda 500, 429 ou 503 sob demanda para testar a UI antes da produção.

O Smart mock gera um formato por endpoint, mas não ramifica a resposta com base na requisição. Para isso, use:

1. Expectativas de mock: regras condicionais com status, cabeçalhos e corpo próprios.
2. Scripts de mock: JavaScript para calcular respostas que regras declarativas não conseguem expressar.

Se você ainda está conhecendo o recurso, comece pela visão geral de mocking de API. Este guia usa o Apidog e parte de uma abordagem contract-first, descrita pela OpenAPI Initiative.

O que é mocking condicional

Um mock condicional é uma regra simples:

Quando a requisição tiver estas características, retorne esta resposta.

No Apidog, você pode trabalhar em duas camadas.

1. Valores dinâmicos no esquema

No esquema de resposta, defina valores fixos ou expressões do Faker.js. Isso controla o conteúdo dos campos, mas mantém um único formato de resposta para o endpoint.

2. Expectativas de mock

Uma expectativa é uma resposta nomeada que pode ter condições de correspondência. Cada expectativa possui:

• condições opcionais;
• corpo de resposta;
• código HTTP;
• cabeçalhos;
• atraso de resposta.

Use expectativas para criar ramificações reais: um corpo para um parâmetro de caminho, outro para um cabeçalho ausente e outro para um cenário de erro.

Gere valores dinâmicos em nível de campo

Antes de criar ramificações, configure valores realistas no esquema da resposta. Campos de string podem usar expressões Faker.js no formato {{$category.method}}.

{
  "id": "{{$number.int(min=1000,max=9999)}}",
  "customer": "{{$person.fullName}}",
  "email": "{{$internet.email}}",
  "product": "{{$commerce.productName}}",
  "shippingAddress": "{{$location.streetAddress}}, {{$location.city}}",
  "orderedAt": "{{$date.between(from='2024-01-01',to='2024-12-31',format='yyyy-MM-dd')}}"
}

Você pode parametrizar métodos e combinar texto estático com expressões dinâmicas:

• {{$number.int(min=1000,max=9999)}} limita o intervalo numérico.
• {{$date.between(...)}} controla intervalo e formato da data.
• "1Z{{$string.alphanumeric(length=16)}}" gera um prefixo estático com um sufixo variável.

Para dados regionalizados, configure a localidade do mock. Consulte a referência do Faker.js no Apidog para ver os métodos disponíveis. O JSON Schema continua sendo a base para declarar os tipos do contrato.

Esse é o papel do Smart mock: gerar dados dinâmicos. Para decidir qual resposta retornar conforme a requisição, use expectativas.

Passo a passo: POST /login com 200 ou 401

Considere este contrato:

• Endpoint: POST /login
• Corpo: username e password
• Usuário conhecido: retorna 200 com token
• Qualquer outro usuário: retorna 401

1. Abra a aba de mock

O local da configuração depende do modo usado:

• No modo DEBUG (Request-first), abra o endpoint e clique na aba Mock.

• No modo DESIGN (Design-first), abra o endpoint e clique na aba Advanced mock.

As duas opções exibem a mesma lista de expectativas. Se necessário, baixe o Apidog e crie ou importe o endpoint antes de continuar.

2. Crie a expectativa de sucesso

Clique em Nova expectativa e configure:

• Nome da expectativa: login-success
• Tipo de condição: parâmetro de corpo
• Nome/caminho JSON: username
• Operador: igual a
• Valor: [e-mail]

Para propriedades aninhadas, use caminhos com ponto. Por exemplo, user.email.

Em Dados de resposta, adicione:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "[e-mail]",
    "role": "member"
  }
}

Salve a expectativa. O status padrão é 200, então nenhuma alteração adicional é necessária para esse caso.

3. Crie a expectativa de falha

Clique novamente em Nova expectativa e configure:

• Nome da expectativa: login-failure
• Condições: deixe em branco
• Dados de resposta:

{
  "error": "invalid_credentials",
  "message": "Username or password is incorrect."
}

Abra a aba Mais e altere o Código de Status HTTP para 401.

Nessa mesma aba, você também pode configurar:

• Atraso de Resposta, em milissegundos;
• cabeçalhos personalizados;
• simulações de latência, como 400ms, para testar spinners e estados de carregamento.

4. Ordene as expectativas

As expectativas são avaliadas de cima para baixo. A primeira correspondência vence.

A ordem correta é:

1. login-success
2. login-failure

A regra login-failure não possui condições e funciona como um catch-all. Se ela ficar acima da regra de sucesso, responderá a todas as requisições e o 200 nunca será retornado.

5. Teste os dois cenários

Copie a URL de mock do endpoint e execute:

# Usuário conhecido -> 200 com token
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

# Qualquer outro usuário -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"whatever"}'

Passo a passo: estados diferentes em /orders/{id}

Agora, crie respostas diferentes para um parâmetro de caminho. O objetivo é renderizar estados da UI sem depender de um backend ativo.

Configure uma expectativa por estado.

Pedido enviado

Crie a expectativa order-shipped:

• Condição: parâmetro de caminho id igual a 5001
• Dados de resposta:

{
  "id": 5001,
  "status": "shipped",
  "total": 129.9,
  "trackingNumber": "1Z{{$string.alphanumeric(length=16)}}",
  "shippedAt": "{{$date.recent(days=3,format='yyyy-MM-dd')}}"
}

Pedido cancelado

Crie a expectativa order-cancelled:

• Condição: parâmetro de caminho id igual a 5002
• Dados de resposta:

{
  "id": 5002,
  "status": "cancelled",
  "total": 0,
  "cancelledAt": "{{$date.recent(days=1,format='yyyy-MM-dd')}}",
  "refundIssued": true
}

Adicione um fallback

Por último, adicione uma expectativa sem condições que retorne um pedido pendente genérico. Assim, qualquer ID não mapeado ainda recebe uma resposta válida.

Mantenha a ordem:

1. regras específicas, como order-shipped e order-cancelled;
2. regra genérica sem condição.

Você também pode combinar condições. Por exemplo, adicione uma condição de cabeçalho à condição do parâmetro id. Nesse caso, ambas devem ser verdadeiras, pois o Apidog combina condições com lógica AND.

Além de corpo e parâmetros de caminho, as condições podem verificar:

• parâmetros de consulta;
• cabeçalhos;
• cookies;
• endereços IP.

Force erros sob demanda

Você não precisa de um backend indisponível para testar fluxos de erro. Crie uma expectativa acionada por um cabeçalho controlado pelo cliente.

Por exemplo, para forçar um 500:

• Condição: cabeçalho X-Mock-Scenario igual a server-error
• Código de Status HTTP: 500
• Dados de resposta:

{
  "error": "internal_error",
  "requestId": "{{$string.uuid}}",
  "message": "Something went wrong on our end. Please retry."
}

Com isso, o endpoint retorna o comportamento padrão quando o cabeçalho não existe e retorna 500 quando ele é enviado:

curl https://<your-mock-host>/orders/5001 \
  -H "X-Mock-Scenario: server-error"

A mesma abordagem funciona para:

• 404 para recursos inexistentes;
• 429 para testar rate limiting;
• 503 para indisponibilidade temporária.

Para 429, configure também o cabeçalho Retry-After na aba Mais. Se você valida esses cenários em automações, combine essa configuração com o guia de asserções de API.

Em projetos compartilhados, cada expectativa pode ser ativada ou desativada separadamente nos mocks local e em nuvem. Por exemplo, mantenha uma regra de 500 ativa localmente e desative-a no mock em nuvem usado pelo restante da equipe.

Quando usar scripts de mock

Expectativas são declarativas: elas correspondem a condições e retornam respostas predefinidas. Use um script de mock quando precisar calcular dados a partir da requisição.

Casos típicos:

• somar itens de um pedido;
• calcular impostos;
• criar campos derivados;
• alterar a estrutura da resposta com base em várias entradas.

O script fica na seção Mock Script, no fim da aba Mock, e precisa ser ativado.

As variáveis globais disponíveis são:

• $$.mockRequest: acesso à requisição de entrada;
• $$.mockResponse: configuração da resposta de saída.

$$.mockRequest fornece:

• getParam(key);
• headers;
• cookies;
• body;
• formdata;
• urlencoded.

$$.mockResponse fornece:

• setBody();
• setCode();
• setDelay();
• json();
• propriedades headers e code.

Exemplo: calcular total do pedido

O script abaixo lê os itens enviados, calcula subtotal, imposto e total, além de reutilizar o cabeçalho x-currency da requisição.

const body = $$.mockRequest.body;
const items = body.items || [];

const subtotal = items.reduce((sum, item) => {
  return sum + item.price * item.quantity;
}, 0);

const currency = $$.mockRequest.headers["x-currency"] || "USD";

$$.mockResponse.setCode(201);
$$.mockResponse.setBody({
  orderId: Math.floor(Math.random() * 90000) + 10000,
  currency: currency,
  subtotal: subtotal,
  tax: Number((subtotal * 0.08).toFixed(2)),
  total: Number((subtotal * 1.08).toFixed(2))
});

O fluxo é:

1. o Smart mock gera uma resposta inicial;
2. o script lê $$.mockRequest e a resposta atual;
3. o script aplica a lógica;
4. o script altera corpo, status, atraso ou cabeçalhos;
5. o mock retorna o resultado final.

Para expandir a lógica, consulte a referência JavaScript da MDN.

Regra importante: scripts e expectativas não se combinam

Scripts de mock funcionam somente com o Smart mock. Eles não são aplicados a expectativas de mock nem a exemplos de resposta.

Em outras palavras:

• se uma expectativa corresponder, o script não será executado;
• use expectativas para ramificações baseadas em regras;
• use scripts para respostas calculadas a partir de dados do Smart mock.

Escolha uma abordagem por endpoint conforme a necessidade.

Entenda a prioridade das respostas

Para cada requisição, o Apidog segue esta ordem:

1. Verifica as expectativas de mock de cima para baixo.
2. Retorna a resposta da primeira expectativa cujas condições correspondem.
3. Se nenhuma expectativa corresponder, usa a prioridade do método Mock definida em Project Settings → Feature Settings → Mock Settings.
4. Nesse fallback, o Smart mock — e qualquer script associado a ele — gera a resposta.

Na prática:

• coloque regras mais específicas no topo;
• deixe regras genéricas abaixo;
• use uma expectativa sem condições no fim quando quiser um fallback explícito;
• deixe o Smart mock responder aos casos restantes.

Veja também os casos de uso de mocking de API para escolher a camada mais adequada para cada cenário.

Armadilhas comuns

Antes de configurar seus mocks, considere estas restrições:

• Condições de parâmetros não aceitam {{variáveis}}. Variáveis de projeto e ambiente não estão disponíveis dentro de expectativas de mock.
• Condições para corpo aceitam apenas JSON, não XML.
• Para corpos JSON, informe a propriedade pelo caminho JSON no campo de nome, como user.email.
• O formato configurado na condição deve corresponder ao formato definido na especificação da API.
• Endpoints form-data devem usar condições form-data, não JSON.
• Scripts de mock não possuem função de log.
• O objeto pm não está disponível em scripts de mock.
• Variáveis do Apidog não podem ser usadas dentro dos scripts; mantenha a lógica autocontida.

A documentação não indica restrições de plano para esses recursos. A diferença entre mock local e em nuvem é funcional: as expectativas podem ser ativadas ou desativadas de forma independente em cada ambiente.

Automatize o fluxo com o Apidog CLI

O mecanismo de mock é disponibilizado pela interface e pelas URLs de mock local ou em nuvem. Não há um comando CLI para iniciar um servidor de mock.

O Apidog CLI ajuda a manter atualizados os recursos que alimentam os mocks: endpoints, esquemas e cenários de teste.

Como as respostas de mock são geradas a partir do esquema, a qualidade do mock acompanha a qualidade da especificação. Atualize o contrato, sincronize o projeto e mantenha a resposta mockada alinhada sem reconfigurar tudo manualmente.

Depois de usar o mock para desbloquear o frontend, execute os cenários do mesmo projeto em CI para validar o backend real:

apidog run -t <scenario_id> -e <env_id> -r cli

Esse comando executa os cenários e reporta os resultados, mantendo mock e validação baseados na mesma fonte de verdade.

Consulte o guia de instalação do Apidog CLI e o passo a passo para usar o Apidog CLI no GitHub Actions.

Perguntas frequentes

Por que minha expectativa é ignorada?

Normalmente, o problema é a ordem ou o formato da condição.

As expectativas são avaliadas de cima para baixo. Uma regra ampla, sem condições, posicionada acima de uma regra específica captura todas as requisições.

Também confirme que:

• o corpo segue o formato definido na API;
• corpos JSON usam caminhos JSON;
• endpoints de formulário usam condições form-data.

A visão geral de mocking de API pode ajudar a revisar a configuração básica.

Posso usar um script de mock e uma expectativa na mesma resposta?

Não. Scripts de mock funcionam apenas com Smart mock.

Se uma expectativa corresponder, ela retorna a resposta e o script não é executado. Use expectativas para regras condicionais e scripts para respostas calculadas.

Como retorno 401 ou 500 sem alterar o 200 padrão?

Crie uma expectativa dedicada com uma condição controlada pelo cliente, como um cabeçalho. Depois, abra a aba Mais e defina o código HTTP desejado.

A resposta padrão continua retornando 200; o erro é acionado apenas quando a condição corresponde.

Posso usar variáveis de ambiente nas condições?

Não. Valores como {{variável}} não estão disponíveis em expectativas de mock. Use valores literais nas condições.

O que ocorre quando nenhuma expectativa corresponde?

O Apidog usa a prioridade do método Mock em Project Settings → Feature Settings → Mock Settings. Nesse fallback, o Smart mock gera a resposta a partir do esquema.

Se precisar de um fallback específico, crie uma expectativa sem condições e coloque-a no fim da lista.

Conclusão

Use o Smart mock para gerar respostas realistas a partir do contrato. Use expectativas de mock quando a resposta depender de um se:

• 200 para um usuário conhecido e 401 para os demais;
• corpos diferentes para cada estado de pedido;
• 500 sob demanda para testar a interface.

Use scripts de mock apenas quando precisar calcular uma resposta a partir da requisição. E mantenha sempre a prioridade em mente: expectativas específicas primeiro, Smart mock depois.

Baixe o Apidog para criar seu primeiro mock condicional.