Testes que dependem de uma API ativa são testes que falham pelos motivos errados. Um servidor de homologação que cai, um limite de taxa de terceiros que entra em ação, um colega de equipe que altera um registro, e de repente sua suíte fica vermelha mesmo que seu código esteja bom. Simular a API remove essa fragilidade. Você substitui o endpoint real por um substituto controlado que retorna exatamente a resposta que você pede, sempre.
Este guia detalha os passos reais para simular uma API para testes. Você definirá um esquema, gerará respostas simuladas, apontará seu código de teste para o mock e cobrirá os caminhos de erro que um servidor real raramente produz sob demanda. Os exemplos usam uma pequena API de gerenciamento de pedidos, mas o fluxo de trabalho se aplica a qualquer serviço REST ou GraphQL.
Quando simular a API é a escolha certa
Simule a API quando o que você deseja testar é o seu próprio código, não a rede. Testes de unidade e a maioria dos testes de integração se enquadram nesta categoria. Você quer saber se seu cliente interpreta um 200 corretamente, tenta novamente em um 503 e exibe uma mensagem clara em um 404. Nada disso exige um servidor real.
Mantenha a API real para testes de contrato e uma camada fina de verificações ponta a ponta. Estes existem para confirmar que o mock ainda corresponde à realidade. Se você simular tudo e nunca verificar com o serviço ativo, sua suíte permanecerá verde enquanto a produção quebra. A divisão é aproximadamente: simular para velocidade e isolamento, acessar o serviço real para confirmar o contrato. Para uma análise mais aprofundada de onde cada um se encaixa, veja esta análise de cenários onde a simulação de API compensa e a distinção entre um servidor mock e um servidor real.
O fluxo de trabalho de cinco passos em resumo
Simular uma API para teste é sempre os mesmos cinco movimentos, independentemente da linguagem ou framework:
- Defina o esquema para que o mock espelhe a forma da resposta real.
- Gere respostas simuladas, estáticas ou dinâmicas, a partir desse esquema.
- Execute um servidor mock que sirva essas respostas em uma URL.
- Aponte seus testes para o mock tornando a URL base configurável.
- Teste os caminhos de erro que o servidor real não produzirá sob demanda.
O resto deste guia detalha cada passo com um exemplo concreto: uma pequena API de gerenciamento de pedidos com um endpoint GET /orders/{id}. Mantenha esse endpoint em mente como o fio condutor.
Passo 1: Definir o esquema
Um mock só é útil se espelhar a forma da resposta real. Comece com um esquema. Se sua API já possui um documento OpenAPI, use-o. Caso contrário, escreva um para o endpoint em teste. Aqui está uma definição simplificada para GET /orders/{id}:
paths:
/orders/{id}:
get:
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
'200':
content:
application/json:
schema:
type: object
properties:
id: { type: string }
status: { type: string, enum: [pending, shipped, delivered] }
total: { type: number }
items: { type: array, items: { type: object } }
'404':
description: Order not found
O esquema tem duas funções. Ele informa ao mock quais campos retornar e fornece uma única fonte da verdade. Quando o backend altera o contrato, você atualiza o esquema e todos os mocks derivados dele permanecem precisos. A simulação baseada em esquema é o que mantém o teste de contrato de API honesto.
Passo 2: Gerar respostas simuladas
Você tem duas maneiras de produzir o corpo da resposta.
Respostas estáticas são JSON fixo. Você escreve o payload exato uma vez e o mock o retorna inalterado. Elas são previsíveis e fáceis de afirmar, o que as torna ideais para testes de unidade onde você deseja um valor conhecido.
Respostas dinâmicas são geradas por requisição. Em vez de codificar "total": 149.99, o mock preenche campos com valores realistas gerados: um UUID para id, um membro de enum aleatório para status, um valor monetário plausível para total. Dados dinâmicos capturam bugs que um único payload fixo oculta, como um parser que quebra em strings longas ou campos nulos inesperados.
A maioria das equipes usa ambos. Payloads estáticos para testes com muitas asserções, geração dinâmica para cobertura no estilo fuzz. Com Apidog, você não precisa escrever nenhum deles manualmente. O Apidog lê o esquema e gera automaticamente um endpoint mock, combinando nomes de campos como email, phone ou avatar com o tipo de dado correto. Você aponta um navegador para a URL do mock e obtém uma resposta válida imediatamente.
Quando você escreve payloads manualmente, mantenha-os realistas. Um pedido de teste com "total": 0 e um array items vazio passa por um parser ingênuo, mas esconde bugs. Use valores que se assemelham à produção: um total com aparência real, dois ou três itens de linha, um status que realmente esteja no enum. Quanto mais próximos os dados simulados forem do que uma requisição real retorna, mais seu teste vale a pena.
Passo 3: Executar o servidor mock
Uma resposta simulada não serve para nada até que algo a sirva. Você tem duas opções de hospedagem.
Um servidor mock local é executado em sua máquina, geralmente em uma porta como localhost:4010. É rápido, funciona offline e é o padrão para testes de unidade e integração. Ferramentas leves como Prism iniciam um diretamente de um arquivo OpenAPI:
prism mock openapi.yaml
# Mock server listening on http://127.0.0.1:4010
Um servidor mock na nuvem possui uma URL pública. Use-o quando um aplicativo móvel, um runner de CI ou um colaborador externo precisar chamar o mock sem acesso ao seu laptop. O Apidog oferece a cada projeto uma URL de Cloud Mock hospedada, para que um colega de equipe em outra rede possa acessar o mesmo endpoint que você.
Para execuções de teste, prefira o local. Ele não tem latência de rede e nenhum estado compartilhado, então duas compilações nunca colidem. Use a opção de nuvem para demonstrações e testes entre dispositivos.
Passo 4: Aponte seus testes para o mock
Agora, conecte o código de teste ao mock em vez da produção. A abordagem mais limpa é uma URL base configurável. Leia-a de uma variável de ambiente para que o mesmo arquivo de teste seja executado contra o mock localmente e a API real em um trabalho de contrato.
// orderClient.test.js
import { getOrder } from './orderClient.js';
const BASE_URL = process.env.API_BASE_URL || 'http://127.0.0.1:4010';
test('parses a shipped order', async () => {
const order = await getOrder('order_8842', BASE_URL);
expect(order.status).toBe('shipped');
expect(typeof order.total).toBe('number');
});
O cliente recebe a URL base como argumento; nada no código de produção sabe que está sendo simulado. No CI, você define API_BASE_URL para o endereço do mock antes da execução da suíte. Esse padrão mantém a simulação completamente fora da lógica do seu aplicativo, que é onde ela pertence. Se você executa testes através de um pipeline, a mesma ideia se aplica ao automatizar testes de API em CI/CD.
Passo 5: Testar os caminhos de erro
Este é o passo que a maioria das equipes pula, e é o que mais compensa. Um servidor real raramente retorna um 500 quando você quer. Um mock retorna um sob comando.
Configure o mock para servir respostas de falha específicas e, em seguida, verifique se seu cliente lida com cada uma delas:
| Cenário | Mock retorna | O que você verifica |
|---|---|---|
| Registro ausente | 404 |
Cliente lança um erro claro de "não encontrado" |
| Falha no servidor | 500 |
Cliente tenta novamente, então exibe um fallback |
| Limite de taxa atingido | 429 com Retry-After |
Cliente aguarda o tempo certo |
| Resposta lenta | 200 após 5s de atraso |
Cliente atinge o tempo limite e se recupera |
| Corpo malformado | 200 com JSON quebrado |
Cliente falha graciosamente, sem travar |
As regras avançadas de mock do Apidog permitem retornar respostas diferentes com base na solicitação, de modo que uma solicitação para order_404 resulta em um 404, enquanto qualquer outro ID retorna um 200 normal. Isso lhe dá um único endpoint de mock cobrindo tanto o caminho feliz quanto as falhas. Combine isso com assertivas de API robustas e sua suíte verificará o comportamento, não apenas os códigos de status.
Organizando mocks em uma suíte de testes crescente
Um único endpoint mock é fácil. Uma centena deles, espalhados por uma suíte, é onde as equipes perdem o controle. Alguns hábitos mantêm o conjunto gerenciável.
Agrupe os mocks pelo serviço real que eles representam, não pelo teste que os utiliza. Quando a API de pagamento muda, você quer um único lugar para atualizar, não vinte arquivos de teste. Nomeie os fixtures mock de acordo com o cenário que eles representam, como order-shipped ou order-rate-limited, para que um teste falho seja lido claramente. Mantenha as definições mock no controle de versão ao lado dos testes, pois um mock faz parte do teste e merece a mesma revisão.
Resista à tentação de dar a cada teste seu próprio payload personalizado. A maioria dos testes deseja o mesmo objeto de pedido realista com um campo alterado. Defina uma resposta base uma vez e sobrescreva apenas o campo em teste. Isso mantém a suíte legível e significa que uma alteração de contrato afeta uma definição base em vez de cópias espalhadas. A mesma disciplina que torna uma suíte de testes para automação de API sustentável se aplica diretamente aos mocks por trás dela.
Mantendo o mock honesto
Um mock se desvia. O backend adiciona um campo, renomeia total para amount ou altera um enum, e seu mock continua retornando a forma antiga. Os testes passam; a produção falha. Esta é a maneira mais comum de a simulação dar errado, e é silenciosa. Nada em sua suíte reclama, porque a suíte está medindo o mock contra si mesmo.
Dois hábitos previnem isso. Primeiro, derive o mock do mesmo esquema que o backend publica, para que uma alteração de contrato atualize ambos de uma vez. Um mock gerado a partir de um arquivo OpenAPI se regenera quando esse arquivo muda; um mock digitado manualmente não. Segundo, execute um pequeno conjunto de testes de contrato contra a API real em um cronograma. O único trabalho deles é confirmar que a resposta ao vivo ainda corresponde ao esquema que seus mocks usam. Quando eles falham, você sabe que o mock está desatualizado antes que os usuários saibam.
Também ajuda revisar mocks durante a revisão de código. Quando um pull request altera uma resposta da API, o revisor deve verificar se o mock correspondente também foi alterado. Tratar o mock como parte do contrato, em vez de um auxiliar de teste descartável, é o que mantém uma suíte simulada confiável ao longo de meses de mudanças.
Se você deseja um único ambiente que contenha o esquema, gera o mock e executa os testes contra ele, Baixe o Apidog. Ele mantém o design, o servidor mock e a suíte de testes sincronizados, para que o mock contra o qual você testa seja sempre o contrato atual. Para opções mais amplas, compare as ferramentas neste resumo de ferramentas de simulação de API REST.
Perguntas frequentes
Devo simular a API para todos os testes?
Não. Simule para testes de unidade e integração onde você está verificando seu próprio código. Mantenha um pequeno conjunto de testes de contrato e ponta a ponta que acessam a API real, pois estes confirmam que seu mock ainda corresponde à produção. Simular tudo esconde desvios de contrato.
Qual a diferença entre uma resposta mock estática e dinâmica?
Uma resposta estática é um payload JSON fixo que nunca muda, o que é bom para asserções previsíveis. Uma resposta dinâmica é gerada por solicitação com valores realistas, o que captura bugs que um único payload fixo perderia. A maioria das equipes usa ambos.
Como garanto que meu mock permaneça preciso?
Gere o mock a partir do mesmo esquema que o backend usa, idealmente um documento OpenAPI. Em seguida, execute testes de contrato agendados contra a API real para confirmar que a resposta ao vivo ainda corresponde a esse esquema. Se eles falharem, seu mock precisa ser atualizado.
Um mock pode simular respostas lentas ou com falha?
Sim, e esta é uma das razões mais fortes para simular. Você pode configurar um mock para retornar um 500, um 429 com um cabeçalho Retry-After ou um 200 atrasado. Isso permite verificar a lógica de repetição e os tempos limite que um servidor real saudável nunca acionaria sob demanda.
Servidor mock local ou servidor mock na nuvem para testes?
Use um servidor mock local para execuções de teste. É rápido, não tem latência de rede e evita estado compartilhado entre builds. Use um mock hospedado na nuvem quando um dispositivo móvel, um runner de CI ou um colaborador externo precisar acessar o mock sem acesso à sua máquina.