nock: Node.js HTTP 요청 모킹 (노코드 대안 포함)

타사 API가 다운되거나 느리거나 호출 제한에 걸려 Node.js 테스트가 실패하는 경우, 이는 코드 문제가 아니라 의존성 문제입니다. 해결책은 HTTP 계층을 모킹하여 단위 테스트가 항상 동일하게 실행되도록 하는 것이며, 대부분의 Node 개발자가 이를 위해 선택하는 npm 패키지는 nock입니다. 이 가이드는 nock이 무엇인지, 간단한 예제, 그리고 인-프로세스 가로채기보다 공유 모의 서버가 더 적합한 경우를 설명합니다. 전체 라이브러리 참조는 nock GitHub 저장소에서 확인할 수 있습니다.

버튼

nock이란 무엇인가요?

nock은 Node.js를 위한 HTTP 서버 모킹 및 기대 라이브러리입니다. 런타임에 Node의 http 및 https 모듈을 재정의하여 작동하므로, 코드에서 발생하는 모든 외부 요청을 가로채서 미리 정의된 응답으로 처리할 수 있습니다. 아무것도 컴퓨터를 벗어나지 않습니다. 네트워크 호출은 전혀 발생하지 않습니다.

이는 단위 테스트에 중요합니다. 외부 API를 호출하는 함수를 테스트할 때 실제 서비스를 호출하고 싶지 않을 것입니다. 실제 호출은 느리고, 비용이 들며, 코드와 관련 없는 이유로 실패할 수 있고, 테스트 스위트를 비결정적으로 만듭니다. nock을 사용하면 "내 코드가 이 URL로 GET 요청을 할 때, 이 정확한 JSON과 이 상태 코드를 반환하라"고 지정할 수 있습니다. 그런 다음 테스트는 함수가 해당 응답을 어떻게 처리하는지 확인합니다.

nock은 Node.js 전용입니다. 네이티브 HTTP 스택에 연결되므로 fetch, axios, got, node-fetch 및 http/https를 기반으로 구축된 모든 것과 함께 작동합니다. 매주 수백만 건의 다운로드를 기록하고 있으며, 수년 동안 백엔드 테스트를 위한 기본 선택이었습니다. 프로덕션에서는 절대 실행되지 않고 테스트에서만 실행되므로 개발 종속성으로 설치합니다.

간단한 nock 예제

API에서 사용자를 가져오는 함수가 있다고 가정해 봅시다. 함수는 다음과 같습니다.

// 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();
}

이제 요청을 가로채기 위해 nock을 사용하는 테스트입니다.

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

test('API가 응답할 때 사용자를 반환합니다', 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' });
});

위에서 아래로 읽어보세요. nock('https://api.example.com')는 가로챌 호스트를 설정합니다. .get('/users/42')는 메서드와 경로를 일치시킵니다. .reply(200, {...})는 반환할 상태와 본문을 정의합니다. getUser(42)가 실행되면 실제 네트워크 호출이 대체되고 미리 정의된 응답이 반환됩니다.

사람들이 테스트하는 것을 잊는 부분인 오류도 동일한 방식으로 모킹할 수 있습니다.

test('API가 500을 반환할 때 예외를 발생시킵니다', async () => {
  nock('https://api.example.com')
    .get('/users/99')
    .reply(500);

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

불행한 경로를 테스트하는 것이 모킹이 빛을 발하는 부분입니다. 실제 API에서 요청에 따라 500 오류를 안정적으로 반환하도록 만들 수는 없지만, 한 줄로 가짜 오류를 만들 수 있습니다. 오류 시뮬레이션이 주된 목표라면, 500 내부 서버 오류 응답을 모킹하는 방법에 대한 이 가이드가 더 자세히 설명합니다.

알아두면 유용한 nock 기능

기본 사항을 넘어선 후에는 몇 가지 메서드가 계속해서 나타납니다.

.persist()는 여러 호출에 걸쳐 인터셉터를 활성 상태로 유지합니다. 기본적으로 nock은 한 번 일치하면 인터셉터를 제거하는데, 이는 요청이 정확히 한 번 발생했음을 확인하는 데 좋습니다. 한 테스트에서 동일한 엔드포인트가 반복적으로 호출될 때 .persist()를 사용하세요.
.times(n)은 인터셉터가 만료되기 전에 동일한 요청을 지정된 횟수만큼 일치시킵니다.
.delay(ms)는 느린 응답을 시뮬레이션하여 타임아웃 처리를 테스트할 수 있게 합니다.
정규식 매칭은 호스트나 경로가 고정된 문자열 대신 패턴이 되도록 허용하며, ID나 쿼리 문자열이 변할 때 유용합니다.
nock.cleanAll()은 모든 인터셉터를 지웁니다. 한 테스트의 모의 설정이 다음 테스트로 유출되지 않도록 테스트 사이에 실행하세요.

일찍부터 길러야 할 습관 중 하나는 모든 모의 설정이 실제로 사용되었는지 확인하는 것입니다. 인터셉터에서 scope.done() (또는 nock.isDone())을 호출하면 예상했던 요청이 발생하지 않았을 경우 테스트가 실패합니다. 이는 조용히 놓친 호출을 시끄러운 실패로 바꿉니다.

nock이 적절한 도구가 아닌 경우

nock은 하나의 작업을 위해 만들어졌으며 그 작업을 잘 수행합니다: 자동화된 테스트 중에 단일 Node 프로세스 내에서 HTTP를 가로채는 것입니다. 필요가 프로세스 경계를 넘어가는 순간, 그 모델은 한계에 부딪히기 시작합니다.

여기에 한계가 있습니다. nock 모의 설정은 테스트 파일 내, 런타임 내, 코드의 언어 내에 존재합니다. 프론트엔드 개발자는 자신의 브라우저를 nock 설정에 연결할 수 없습니다. 모바일 엔지니어는 시뮬레이터에서 이를 호출할 수 없습니다. QA 팀은 이를 대상으로 수동 검사를 실행할 수 없습니다. Postman 컬렉션은 여기에 도달할 수 없습니다. 모의 설정은 Jest 또는 Mocha 프로세스가 실행되는 동안에만 존재하며, 동일한 프로세스 내의 코드에만 유효합니다.

이는 단위 테스트에는 적합하며 nock이 설계된 목적입니다. 그러나 많은 실제 상황에서는 모든 사람이 접근할 수 있는 곳에 모의 설정이 필요합니다.

프론트엔드는 백엔드가 존재하기 전에 엔드포인트를 기반으로 구축해야 합니다.
세 개의 다른 저장소에 있는 세 팀이 동일한 가짜 응답에 동의해야 합니다.
실제 백엔드 없이 통합을 시연하고 싶습니다.
테스터가 코딩 없이 수동으로 엣지 케이스를 테스트하고 싶습니다.

이러한 경우에는 실제 URL에서 수신하고 호출하는 모든 클라이언트에 응답을 반환하는 모의 서버가 필요합니다. 두 가지 아이디어를 저울질하고 있다면, 모의 서버 대 실제 서버와 API 모킹에 대한 더 넓은 설명이 모두 장단점을 제시합니다.

nock 대 호스팅된 모의 서버(Apidog)

이는 경쟁이라기보다는 두 가지 계층으로 생각할 수 있습니다. nock은 단위 테스트를 위한 코드 내 가로채기를 처리합니다. Apidog와 같은 도구는 단일 테스트 프로세스 외부에서 발생하는 모든 것에 대해 공유되고 스키마 기반의 모의 서버를 제공합니다. 많은 팀이 둘 다 사용합니다.

Apidog는 API 디자인에서 직접 모의 서버를 생성합니다. 엔드포인트와 해당 스키마를 정의하면, Apidog는 필드 이름과 유형에서 그럴듯한 데이터를 생성하는 스마트 모의 규칙과 함께 실제 URL에서 실제와 같은 응답을 제공합니다. 테스트 하네스도, 테스트별 설정도, 언어 종속성도 없습니다. URL을 가진 모든 사람이 동일한 응답을 받습니다.

	nock	Apidog 모의 서버
실행 위치	Node 테스트 프로세스 내	실제 URL을 가진 호스팅 서버
가장 적합한 용도	단위 테스트, 오류 시뮬레이션	통합, 수동 테스트, 팀 간 작업
접근 가능 대상	동일 프로세스 내 코드	URL을 가진 모든 클라이언트
설정	각 테스트 파일 내 코드	API 스키마에서 생성
언어	Node.js 전용	모든 클라이언트, 모든 언어
실제 데이터	각 응답을 직접 작성	스키마 및 필드 이름으로부터 스마트 모의 생성
공유	공유 불가	전체 팀이 공유

범위를 명확히 하자면, Apidog는 Jest 또는 Mocha 단위 테스트 내에서 nock을 대체하지 않습니다. 단일 테스트에서 fetch 호출을 가로채고 결과를 확인해야 한다면, nock이 여전히 올바른 도구입니다. Apidog는 모의 설정에 다른 사람들과 다른 도구들이 접근할 수 있는 주소가 필요할 때 개입합니다. 서버 측면에 대한 실습적인 내용은 테스트를 위한 API 모킹 가이드를 참조하십시오. Apidog를 다운로드하여 몇 분 안에 기존 OpenAPI 파일에서 모의를 시작할 수 있습니다.

nock의 다른 대안

nock이 이 분야에서 유일한 라이브러리는 아니며, 적절한 선택은 코드가 실행되는 위치에 따라 달라집니다.

MSW (Mock Service Worker)는 브라우저에서는 서비스 워커를, 서버에서는 Node 인터셉터를 사용하여 네트워크 수준에서 요청을 가로챕니다. 동일한 모의 정의가 양쪽에서 작동하므로, 많은 팀이 이제 풀스택 JavaScript를 위해 기본적으로 이를 선택합니다. 공식 MSW 문서에서 모델을 설명합니다.
Jest 수동 모의는 axios와 같은 모듈을 가짜로 대체할 수 있게 해줍니다. 작은 경우에는 nock보다 간단하지만, 하나의 HTTP 클라이언트에 종속됩니다. Jest 모킹 튜토리얼에서 이 패턴을 다룹니다.
Node 자체 테스트 러너 또는 Sinon과 같은 라이브러리의 내장 테스트 더블은 호출을 하는 함수를 스터브할 수 있지만, nock의 HTTP 수준 매칭 기능을 잃게 됩니다.

결정적인 질문은 항상 같습니다. 단일 프로세스 내의 로직을 테스트하는 것인가, 아니면 네트워크 상에 존재하는 가짜 API가 필요한가? nock과 MSW는 첫 번째 질문에 답합니다. 호스팅된 모의 서버는 두 번째 질문에 답합니다.

자주 묻는 질문

nock은 무료인가요?

네. nock은 MIT 라이선스 하에 오픈 소스이며 npm에서 무료로 설치할 수 있습니다. 개발 종속성으로 추가하고 테스트 스위트에서 비용 없이 사용할 수 있습니다.

nock은 fetch 및 axios와 함께 작동하나요?

네. nock은 Node의 http/https 계층에서 가로채기 때문에, 네이티브 fetch, axios, got, node-fetch를 포함하여 해당 모듈을 기반으로 구축된 모든 클라이언트와 함께 작동합니다. 코드에서 어떤 클라이언트를 사용하든 동일한 인터셉터를 작성합니다.

브라우저에서 nock을 사용할 수 있나요?

아니요. nock은 Node의 HTTP 모듈을 패치하기 때문에 Node.js 전용이며, 이 모듈은 브라우저에 존재하지 않습니다. 브라우저 측 모킹의 경우 MSW를 사용하거나 프론트엔드를 호스팅된 모의 서버에 연결하세요. JavaScript에서 API 모의에 대한 이 개요에서 브라우저 옵션을 설명합니다.

nock과 모의 서버의 차이점은 무엇인가요?

nock은 테스트 프로세스 내에서 요청을 가로채고 실제 포트를 열지 않습니다. 모의 서버는 모든 클라이언트가 호출할 수 있는 실제 URL에서 수신 대기합니다. 단위 테스트에는 nock을 사용하고, 프론트엔드, QA 또는 다른 팀이 동일한 가짜 응답에 접근해야 할 때는 모의 서버를 사용하세요.

마무리

nock은 Node.js 단위 테스트에서 HTTP 모킹을 위한 신뢰할 수 있는 선택입니다. 프로세스 내에서 외부 요청을 가로채고, 정의한 응답을 반환하며, 실제 API에서 트리거할 수 없는 오류 경로를 포함하여 테스트 스위트를 빠르고 결정적으로 만듭니다. 이 목적으로 계속 사용하세요.

모의 설정이 테스트 파일을 벗어나야 할 때, 프론트엔드, QA 또는 다른 팀이 동일한 엔드포인트에 접근해야 할 때는 대신 공유 모의 서버를 사용하세요. Apidog는 API 스키마에서 이를 생성하고 실제 데이터를 라이브 URL에서 제공하므로, 백엔드가 준비되기 전에 모든 사람이 동일한 계약을 기반으로 구축할 수 있습니다. Apidog를 다운로드하고 몇 분 안에 OpenAPI 스펙을 작동하는 모의로 전환하세요.