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 seu endpoint e retorna dados plausíveis: um e-mail com aparência real, um carimbo de data/hora sensato, um nome que não seja xJ8kQ. Para a maioria dos trabalhos de frontend, isso é suficiente para te destravar.

Então você se depara com o caso que o Smart mock não consegue atingir. Você quer que /login retorne 200 para um usuário conhecido e 401 caso contrário. Você quer que /orders/{id} retorne um pedido enviado para um ID e um cancelado para outro. Você quer forçar um 500 sob demanda para que seu tratamento de erros seja exercitado antes de chegar à produção. O Smart mock retorna um formato por endpoint, então ele não consegue criar ramificações na requisição. É essa lacuna que este guia preenche.

O Apidog cobre isso com duas funcionalidades: expectativas de mock para respostas condicionais baseadas em regras, e scripts de mock para lógicas que as regras não conseguem expressar. Este passo a passo mostra ambos com exemplos concretos, e explica a ordem de prioridade para que suas regras personalizadas sempre prevaleçam sobre o Smart mock. Se você é novo nos fundamentos, a visão geral de mocking de API é um bom aquecimento, e o Apidog é a ferramenta que usaremos ao longo deste guia. A OpenAPI Initiative documenta o fluxo de trabalho contract-first que torna tudo isso possível.

O que o mocking condicional realmente significa

Um mock condicional é uma regra: quando a requisição de entrada se parece com isto, retorne aquilo. O Apidog constrói essas regras a partir de duas camadas.

A primeira camada é a customização em nível de campo dentro do esquema do endpoint. Você fixa um campo a um valor específico, ou anexa uma expressão dinâmica do Faker.js para que ele varie a cada chamada. Isso controla o que um campo contém, mas ainda retorna um único formato de resposta para o endpoint.

A segunda camada é a expectativa de mock de resposta completa. Uma expectativa é uma regra nomeada com condições opcionais e seu próprio corpo de resposta, código de status e cabeçalhos. Uma expectativa sem condições retorna dados fixos incondicionalmente. Uma expectativa com condições retorna seus dados apenas quando a requisição corresponde. Empilhe algumas delas e você terá ramificações reais: resposta B quando a requisição corresponde à condição A, um corpo de erro quando um cabeçalho está faltando, um payload diferente por parâmetro de caminho.

Essa segunda camada torna possíveis os estados de erro sob demanda e os corpos de resposta por requisição. O restante deste guia aborda isso.

Valores dinâmicos em nível de campo primeiro

Antes das ramificações, é útil ver como um único campo obtém seu valor, pois suas respostas condicionais reutilizarão a mesma sintaxe.

Dentro do esquema de um endpoint, qualquer campo de string pode conter uma expressão Faker.js escrita como {{$category.method}}. O Apidog a resolve novamente a cada chamada de mock, usando os tipos de campo que sua definição de JSON Schema já declara.

{
  "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')}}"
}

Métodos parametrizados funcionam, então {{$number.int(min=1000,max=9999)}} limita o valor e {{$date.between(...)}} fixa um intervalo e formato. Você pode concatenar texto estático e múltiplas expressões em um campo, que é como o endereço acima é construído. Se você precisar de dados específicos de região, o Apidog suporta locais de mock personalizáveis para que seus nomes, endereços e números de telefone correspondam a um determinado idioma ou país. A referência do Faker.js no Apidog cobre o catálogo completo de métodos.

Este é o território do Smart mock. É dinâmico, mas não é condicional. Para criar ramificações na requisição, você sobe para as expectativas.

Passo a passo: um endpoint de login que retorna 200 ou 401

O caso canônico: POST /login recebe um corpo JSON com username e password. Um usuário conhecido deve receber 200 com um token. Todos os outros devem receber 401.

Abra a aba correta

Onde você configura isso depende do seu modo de trabalho:

• 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.

Ambos levam à mesma lista de expectativas. Se você quiser acompanhar e ainda não tem o aplicativo, Baixe o Apidog e importe ou crie um endpoint /login primeiro.

Adicione a expectativa de sucesso

Clique em Nova expectativa. Dê a ela um nome de expectativa como login-success. Agora adicione uma condição. Como username reside no corpo da requisição JSON, você o corresponde como um parâmetro de corpo: coloque o caminho JSON da propriedade alvo, username, no campo de nome, e defina a condição para ser igual a alice@example.com.

As condições de parâmetro de corpo são apenas JSON, e são correspondidas através do caminho JSON no campo de nome, então propriedades aninhadas usam caminhos de ponto como user.email. Preencha os dados de resposta com o payload de sucesso:

{
  "token": "mock-jwt-{{$string.uuid}}",
  "user": {
    "id": 4821,
    "username": "alice@example.com",
    "role": "member"
  }
}

Salvar. O Código de Status HTTP padrão é 200, então você não precisa tocar em mais nada para o caminho feliz.

Adicione a expectativa de falha

Clique em Nova expectativa novamente. Nomeie-o como login-failure e deixe suas condições em branco para que ele atue como um 'catch-all' (captura-tudo). Defina seus dados de resposta para o corpo de erro:

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

Este precisa de um status não padrão. Abra a aba Mais da expectativa e defina o Código de Status HTTP para 401. Enquanto estiver lá, note que a aba Mais também é onde você define o Atraso de Resposta em milissegundos (padrão 0) e quaisquer cabeçalhos de resposta personalizados. Um atraso de 400ms é uma maneira barata de garantir que seu spinner de carregamento seja de fato renderizado.

A ordem importa

As expectativas são avaliadas de cima para baixo, e a primeira correspondência ganha. Então login-success deve estar acima de login-failure. Uma requisição com username igual a alice@example.com corresponde à primeira regra e retorna o token. Qualquer outra coisa passa para a regra de falha incondicional e recebe o 401. Se você invertesse a ordem, a regra de condição em branco corresponderia a tudo e seu caso de sucesso nunca seria acionado.

Copie a URL do mock do endpoint e teste ambos os caminhos:

# usuário conhecido -> 200 com um token
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice@example.com","password":"whatever"}'

# qualquer outro -> 401
curl -X POST https://<your-mock-host>/login \
  -H "Content-Type: application/json" \
  -d '{"username":"stranger@example.com","password":"whatever"}'

Passo a passo: diferentes corpos para /orders/{id} por status

O segundo caso comum ramifica em um parâmetro de caminho. Você quer que /orders/{id} retorne um pedido enviado para um ID e um pedido cancelado para outro, para que sua UI possa renderizar todos os estados sem um backend ativo.

Crie uma expectativa por estado. Para cada uma, adicione uma condição no parâmetro de caminho id, então preencha os dados de resposta correspondentes.

Expectativa order-shipped, condição: parâmetro de caminho id igual a 5001.

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

Expectativa order-cancelled, condição: parâmetro de caminho id igual a 5002.

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

Adicione uma expectativa final sem condições que retorne um pedido pendente genérico, para que qualquer outro ID ainda receba uma resposta válida em vez de passar adiante. Ordene as regras específicas acima do 'catch-all', salve, e você terá um mock que renderiza todos os estados de pedido sob demanda. Misturar condições também funciona: adicione uma condição de cabeçalho junto com a condição de caminho e ambas devem ser verdadeiras, pois o Apidog combina múltiplas condições com lógica AND (uma intersecção das condições, nos termos da documentação).

As condições não se limitam a corpo e caminho. Você pode fazer a correspondência por parâmetros de consulta, parâmetros de cabeçalho, parâmetros de cookie e até mesmo endereços IP, o que permite restringir uma resposta a clientes específicos durante um teste.

Forçando estados de erro sob demanda

Você não precisa de um backend quebrado para testar respostas com erro. Uma expectativa mais a aba Mais oferece qualquer status que você desejar.

Para forçar um 500, adicione uma expectativa cuja condição seja algo que você controla a partir do cliente, digamos um cabeçalho X-Mock-Scenario igual a server-error. Defina seus dados de resposta para um corpo de erro realista e seu Código de Status HTTP para 500 na aba Mais.

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

Agora, o mesmo endpoint serve um 200 normal por padrão e um 500 sempre que você envia esse cabeçalho. Faça o mesmo para 404, 429 (com um cabeçalho Retry-After definido na aba Mais), ou 503. Seu tratamento de erros de frontend finalmente tem algo para interceptar. Se você faz asserções sobre essas respostas em verificações automatizadas, o guia para asserções de API combina bem com esta configuração.

Um detalhe para projetos compartilhados: cada expectativa pode ser ativada ou desativada independentemente para os ambientes de mock local e na nuvem a partir da lista de expectativas. Assim, você pode manter uma regra de 500 ativa localmente, enquanto a deixa desativada no mock da nuvem que seus colegas de equipe acessam.

Quando as regras não são suficientes: scripts de mock

Expectativas são declarativas. Elas correspondem e retornam, mas não conseguem calcular. Quando você precisa de um campo derivado da requisição, um total somado de itens de linha, ou um corpo que muda de formato com base em várias entradas ao mesmo tempo, você recorre a um script de mock.

Um script de mock é JavaScript que é executado contra a resposta do mock. Ele reside na seção Mock Script na parte inferior da aba Mock e é ativado com um interruptor. O script expõe duas variáveis globais:

• $$.mockRequest: lê a requisição de entrada via getParam(key), além de headers, cookies, body, formdata e urlencoded.
• $$.mockResponse: modela a resposta de saída via setBody(), setCode(), setDelay(), json(), e as propriedades headers e code.

Aqui está um script que calcula o total de um pedido a partir dos itens de linha enviados e retorna o cabeçalho de moeda do chamador:

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 é: o Smart mock gera uma resposta inicial, seu script lê $$.mockRequest e o $$.mockResponse atual, aplica sua lógica, chama $$.mockResponse.setBody() (e setCode, setDelay, ou headers conforme necessário), e o motor retorna o resultado final. A referência JavaScript da MDN é um companheiro sólido se você quiser levar a lógica adiante com métodos de array ou matemática de datas.

A única regra que confunde as pessoas

Scripts de mock funcionam apenas com Smart mock. Eles não se aplicam a expectativas de mock ou exemplos de resposta. Esta é a coisa mais importante a internalizar: você não pode combinar um script de mock com uma resposta baseada em expectativa. Se uma expectativa corresponde à requisição, o script nunca é executado. Portanto, escolha um caminho por endpoint. Use expectativas quando estiver ramificando em condições fixas e retornando corpos predefinidos. Use um script de mock quando precisar de uma saída computada da base gerada pelo Smart mock.

Como a ordem de prioridade é resolvida

Juntando tudo, esta é a ordem que o Apidog segue para qualquer requisição de mock:

1. Ele verifica suas expectativas, de cima para baixo. A primeira expectativa cujas condições correspondem ganha, e sua resposta é retornada. É por isso que regras personalizadas vencem o Smart mock: uma expectativa correspondente ignora tudo abaixo dela.
2. Se nenhuma expectativa corresponder, o Apidog recorre à prioridade do método Mock que você definiu em Project Settings - Feature Settings - Mock Settings. Esse é o nível onde o Smart mock (e qualquer script de mock anexado a ele) produz a resposta.

O modelo mental é simples: regras específicas primeiro, dados gerados em segundo. Ordene suas expectativas do mais específico para o menos, mantenha um 'catch-all' de condição em branco no final se quiser uma correspondência garantida, e deixe o Smart mock lidar com o resto. Para uma exploração mais aprofundada de quando usar cada camada, o guia de casos de uso de mocking de API mapeia cenários comuns para funcionalidades.

Armadilhas a saber antes de lançar

Algumas restrições irão poupar uma sessão de depuração confusa:

• Condições de parâmetro não suportam {{variáveis}}. Variáveis de projeto e ambiente do Apidog não estão disponíveis dentro das expectativas de mock, então use valores literais em suas condições.
• Condições de parâmetro de corpo são apenas JSON, não XML, e devem ser correspondidas via o caminho JSON no campo de nome.
• O formato do corpo da requisição em uma condição precisa corresponder à especificação da API.
• Um endpoint form-data deve ser mockado com posicionamento form-data, não JSON.
• Dentro dos scripts de mock não há função de log, o objeto pm não está disponível (é um ambiente de execução diferente dos scripts de teste), e as variáveis do Apidog não podem ser usadas. Mantenha a lógica do script autocontida.

Nenhuma dessas funcionalidades possui restrição de plano na documentação. A única distinção entre local e nuvem é funcional: a chave de ligar/desligar independente por ambiente descrita anteriormente, não um paywall.

Automatize o fluxo de trabalho com o Apidog CLI

O mocking no Apidog é uma capacidade de GUI e nuvem. O motor de mock serve seus endpoints a partir de URLs de mock locais e na nuvem, e não há comando CLI que levante um servidor de mock em execução. O que o Apidog CLI adiciona é o controle sobre os recursos a partir dos quais esses mocks são construídos.

As respostas de mock são geradas a partir do esquema do endpoint, então a precisão do seu mock acompanha a precisão da sua especificação. O CLI, e os agentes de codificação de IA que o impulsionam (Cursor, Claude Code, Trae, Codex), podem criar e atualizar os endpoints e esquemas em seu projeto. Altere o contrato no código, sincronize-o, e a saída do mock permanece correta sem que ninguém precise reabrir o aplicativo.

Uma vez que o mock tenha desbloqueado o trabalho de frontend, os cenários de teste do mesmo projeto são executados em modo headless na CI para validar o backend real contra o contrato descrito pelo mock:

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

Esse único comando executa seus cenários de teste e reporta os resultados, para que o mock e a verificação compartilhem uma única fonte de verdade. O guia de instalação do Apidog CLI cobre a configuração, e o passo a passo do Apidog CLI em GitHub Actions o conecta a um pipeline.

Perguntas Frequentes

Por que minha expectativa é ignorada, mesmo que a condição pareça correta? Quase sempre é a ordem ou uma incompatibilidade de formato. As expectativas são avaliadas de cima para baixo e a primeira correspondência ganha, então uma regra de condição em branco ampla posicionada acima de uma específica irá 'engolir' a requisição. Confirme também que o formato do corpo corresponde à especificação (caminho JSON para corpos JSON, posicionamento form-data para endpoints de formulário). A visão geral de mocking de API aborda os conceitos básicos de configuração, caso você queira verificar novamente.

Posso usar um script de mock e uma expectativa de mock na mesma resposta? Não. Scripts de mock funcionam apenas com Smart mock. Eles são ignorados por expectativas de mock e exemplos de resposta. Se uma expectativa corresponde, o script nunca é executado, então escolha uma abordagem por endpoint: expectativas para ramificações baseadas em regras, scripts para saída computada.

Como retorno um 401 ou 500 sem quebrar o 200 padrão? Adicione uma expectativa dedicada com uma condição que você controla a partir do cliente (um cabeçalho funciona bem), então abra sua aba Mais e defina o Código de Status HTTP. A resposta padrão permanece 200; o erro é acionado apenas quando a condição corresponde.

As condições podem usar minhas variáveis de ambiente? Não. Valores de {{variável}} do Apidog não estão disponíveis dentro das expectativas de mock, e as condições de parâmetro não suportam {{variáveis}}. Use valores literais nas condições.

O que acontece quando nenhuma expectativa corresponde? O Apidog recorre à prioridade do método Mock em Project Settings - Feature Settings - Mock Settings, onde o Smart mock gera uma resposta a partir do seu esquema. Adicionar uma expectativa 'catch-all' de condição em branco é a maneira de garantir um fallback específico em vez disso.

Concluindo

O Smart mock lida com o caso comum, e as expectativas de mock lidam com tudo que envolve um se: 200 para um usuário conhecido e 401 caso contrário, um corpo de pedido diferente por status, um 500 sob demanda. Recorra a um script de mock apenas quando precisar de uma saída computada que as regras não conseguem expressar, e lembre-se de que ele é executado apenas contra o Smart mock. Tenha em mente a ordem de prioridade (expectativas específicas primeiro, dados gerados em segundo) e seus mocks ramificarão exatamente como as APIs reais. Baixe o Apidog para construir seu primeiro mock condicional, gratuito, sem necessidade de cartão de crédito.