O que é nock? Como mockar requisições HTTP em Node.js (com alternativa sem código)

Se seus testes Node.js falham porque uma API de terceiros está inoperante, lenta ou com limite de taxa, você não tem um problema de código. Você tem um problema de dependência. A solução é simular a camada HTTP para que seus testes unitários sejam executados da mesma forma sempre, e nock é o pacote npm que a maioria dos desenvolvedores Node utiliza. Este guia explica o que é nock, mostra um pequeno exemplo funcional e aborda onde um servidor de simulação compartilhado se encaixa melhor do que a interceptação em processo. Para a referência completa da biblioteca, o repositório nock no GitHub é a fonte da verdade.

O que é nock?

nock é uma biblioteca de simulação e expectativas para servidores HTTP em Node.js. Ele funciona substituindo os módulos http e https do Node em tempo de execução, para que qualquer requisição de saída que seu código faça possa ser interceptada e respondida com uma resposta pré-definida. Nada sai da sua máquina. A chamada de rede nunca acontece.

Isso é importante para testes unitários. Quando você testa uma função que chama uma API externa, você não quer atingir o serviço real. Chamadas reais são lentas, custam dinheiro, podem falhar por motivos não relacionados ao seu código e tornam sua suíte de testes não determinística. nock permite que você diga "quando meu código fizer uma requisição GET para esta URL, retorne este JSON exato com este código de status". Seu teste então verifica como sua função lida com essa resposta.

nock é exclusivo para Node.js. Ele se conecta à pilha HTTP nativa, então funciona com fetch, axios, got, node-fetch e qualquer outra coisa construída sobre http/https. Possui milhões de downloads semanais e tem sido uma escolha padrão para testes de backend por anos. Você o instala como uma dependência de desenvolvimento porque ele só roda em testes, nunca em produção.

Um pequeno exemplo de nock

Digamos que você tenha uma função que busca um usuário de uma API. Aqui está a função:

// user-service.js
export async function getUser(id) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  if (!res.ok) throw new Error(`Request failed: ${res.status}`);
  return res.json();
}

Agora, aqui está um teste que usa o nock para interceptar a requisição:

// user-service.test.js
import nock from 'nock';
import { getUser } from './user-service.js';

test('retorna o usuário quando a API responde', async () => {
  nock('https://api.example.com')
    .get('/users/42')
    .reply(200, { id: 42, name: 'Ada Lovelace' });

  const user = await getUser(42);
  expect(user).toEqual({ id: 42, name: 'Ada Lovelace' });
});

Leia de cima para baixo. nock('https://api.example.com') define o host que você deseja interceptar. .get('/users/42') corresponde ao método e ao caminho. .reply(200, {...}) define o status e o corpo a serem retornados. Quando getUser(42) é executado, a chamada de rede real é substituída e sua resposta pré-definida é retornada.

Você pode simular erros da mesma forma, que é a parte que as pessoas esquecem de testar:

test('lança um erro quando a API retorna 500', async () => {
  nock('https://api.example.com')
    .get('/users/99')
    .reply(500);

  await expect(getUser(99)).rejects.toThrow('Request failed: 500');
});

Testar o caminho de erro é onde a simulação se paga. Você não consegue fazer uma API ativa retornar um 500 sob demanda de forma confiável, mas você pode simular um em uma única linha. Se a simulação de erros é seu principal objetivo, este passo a passo sobre como simular uma resposta de erro interno de servidor 500 se aprofunda no assunto.

Recursos úteis do nock para conhecer

Alguns métodos surgem constantemente quando você vai além do básico.

• .persist() mantém um interceptor ativo em várias chamadas. Por padrão, o nock remove um interceptor depois que ele é correspondido uma vez, o que é ótimo para afirmar que uma requisição ocorreu exatamente uma vez. Use .persist() quando o mesmo endpoint é atingido repetidamente em um teste.
• .times(n) corresponde à mesma requisição um número definido de vezes antes que o interceptor expire.
• .delay(ms) simula uma resposta lenta para que você possa testar o tratamento de tempo limite.
• Correspondência por RegExp permite que o host ou caminho seja um padrão em vez de uma string fixa, útil quando IDs ou strings de consulta variam.
• nock.cleanAll() limpa todos os interceptadores. Execute-o entre os testes para que as simulações de um teste não vazem para o próximo.

Um hábito que vale a pena desenvolver cedo: certifique-se de que todas as suas simulações foram realmente usadas. Chame scope.done() em um interceptor (ou nock.isDone()) e o teste falhará se uma requisição esperada nunca for disparada. Isso transforma uma chamada perdida silenciosa em uma falha barulhenta.

Onde o nock deixa de ser a ferramenta certa

O nock é feito para um trabalho e o faz bem: interceptar HTTP dentro de um único processo Node durante testes automatizados. No momento em que sua necessidade cruza o limite de um processo, esse modelo começa a se esgotar.

Aqui está a limitação. As simulações do nock vivem dentro do seu arquivo de teste, no seu tempo de execução, na sua linguagem. Um desenvolvedor front-end não pode apontar seu navegador para sua configuração de nock. Um engenheiro mobile não pode acessá-lo de um simulador. Sua equipe de QA não pode realizar verificações manuais nele. Uma coleção do Postman não pode alcançá-lo. A simulação existe apenas enquanto seu processo Jest ou Mocha estiver em execução, e apenas para código nesse mesmo processo.

Isso é bom para testes unitários e exatamente para o que o nock foi projetado. Mas muitas situações reais exigem uma simulação que viva em um lugar onde todos possam alcançá-la:

• O front-end precisa desenvolver contra um endpoint antes que o back-end exista.
• Três equipes em repositórios diferentes precisam concordar com as mesmas respostas falsas.
• Você quer demonstrar uma integração sem um back-end ao vivo.
• Um testador quer investigar casos extremos manualmente, sem precisar de código.

Para esses casos, você precisa de um *servidor* de simulação, algo que escute em uma URL real e retorne respostas para quem o chamar. Se você está pesando as duas ideias, servidor de simulação vs servidor real e a explicação mais ampla sobre simulação de API ambos expõem as vantagens e desvantagens.

nock vs um servidor de simulação hospedado (Apidog)

Pense nisso como duas camadas, em vez de uma competição. O nock lida com a interceptação em código para testes unitários. Uma ferramenta como o Apidog oferece um servidor de simulação compartilhado e orientado a esquema para tudo o que acontece fora de um único processo de teste. Muitas equipes usam ambos.

O Apidog gera um servidor de simulação diretamente do design da sua API. Você define um endpoint e seu esquema, e o Apidog serve respostas realistas em uma URL ao vivo, com regras de simulação inteligentes que produzem dados plausíveis a partir de nomes e tipos de campos. Sem harness de teste, sem configuração por teste, sem bloqueio de linguagem. Qualquer pessoa com a URL obtém as mesmas respostas.

Para ser claro sobre o escopo: o Apidog não substitui o nock dentro dos seus testes unitários com Jest ou Mocha. Se você precisa interceptar uma chamada fetch em um único teste e verificar o resultado, o nock ainda é a ferramenta certa. O Apidog entra em cena quando a simulação precisa de um endereço que outras pessoas e outras ferramentas possam acessar. Para uma visão prática do lado do servidor, consulte o guia prático para simular uma API para testes. Você pode baixar o Apidog e ativar uma simulação a partir de um arquivo OpenAPI existente em poucos minutos.

Outras alternativas ao nock

nock não é a única biblioteca neste espaço, e a escolha certa depende de onde seu código é executado.

• MSW (Mock Service Worker) intercepta requisições no nível da rede usando um service worker no navegador e um interceptor Node no servidor. As mesmas definições de simulação funcionam em ambos, razão pela qual muitas equipes agora o utilizam por padrão para JavaScript full-stack. A documentação oficial do MSW explica o modelo.
• Jest manual mocks permitem que você substitua um módulo como axios por um falso. Isso é mais simples que o nock para um caso pequeno, mas o vincula a um único cliente HTTP. O tutorial de simulação do Jest aborda o padrão.
• Built-in test doubles no próprio executor de testes do Node ou bibliotecas como Sinon podem substituir a função que faz a chamada, embora você perca a correspondência no nível HTTP do nock.

A pergunta decisiva é sempre a mesma. Você está testando a lógica dentro de um processo, ou precisa de uma API falsa que vive na rede? nock e MSW respondem à primeira. Um servidor de simulação hospedado responde à segunda.

Perguntas frequentes

O nock é gratuito?

Sim. nock é de código aberto sob a licença MIT e gratuito para instalar via npm. Você o adiciona como uma dependência de desenvolvimento e o usa em sua suíte de testes sem custo.

O nock funciona com fetch e axios?

Sim. Como o nock intercepta na camada http/https do Node, ele funciona com qualquer cliente construído sobre esses módulos, incluindo o fetch nativo, axios, got e node-fetch. Você escreve o mesmo interceptor, independentemente de qual deles seu código usa.

Posso usar o nock no navegador?

Não. nock é exclusivo para Node.js porque ele corrige os módulos HTTP do Node, que não existem no navegador. Para simulação no lado do navegador, use MSW ou aponte seu front-end para um servidor de simulação hospedado. Esta visão geral de APIs de simulação em JavaScript aborda as opções do navegador.

Qual a diferença entre nock e um servidor de simulação?

nock intercepta requisições dentro do seu processo de teste e nunca abre uma porta real. Um servidor de simulação escuta em uma URL real que qualquer cliente pode chamar. Use nock para testes unitários; use um servidor de simulação quando o front-end, QA ou outras equipes precisam acessar as mesmas respostas falsas.

Conclusão

nock é a escolha confiável para simulação HTTP em testes unitários Node.js. Ele intercepta requisições de saída em processo, retorna as respostas que você define e torna sua suíte de testes rápida e determinística, incluindo os caminhos de erro que você não conseguiria acionar em uma API ao vivo. Continue usando-o para isso.

Quando a simulação precisa sair do seu arquivo de teste, quando o front-end, o QA ou outra equipe precisa acessar o mesmo endpoint, recorra a um servidor de simulação compartilhado. O Apidog gera um a partir do esquema da sua API e serve dados realistas em uma URL ao vivo, para que todos desenvolvam com base no mesmo contrato antes que o backend esteja pronto. Baixe o Apidog e transforme sua especificação OpenAPI em uma simulação funcional em minutos.