Blog

Node.js Supertest로 HTTP API 테스트하는 방법

Oliver Kingsley

Oliver Kingsley

14 August 2025

Node.js Supertest로 HTTP API 테스트하는 방법

빠르게 진화하는 API 환경에서 팀은 두 가지를 필요로 합니다: 코드 수준에서의 빠른 피드백과 환경 전반에 걸친 신뢰할 수 있는 엔드투엔드 유효성 검사. Supertest는 첫 번째 요구사항인 Node.js 서비스를 위한 초고속 HTTP 어설션을 제공합니다. 그리고 역할 간 협업, 시나리오 테스트 실행, 의존성 모의(mocking), 문서 발행을 할 준비가 되면, Apidog와 같은 API 테스트 플랫폼이 그림을 완성합니다. 이 공식적이고 객관적인 가이드는 Supertest를 사용하여 API를 테스트하는 방법, Supertest가 빛을 발하는 지점, 그리고 Apidog와 함께 사용하여 자신감 있는 배포를 가속화하는 방법을 설명합니다.

Apidog
button

Supertest란 무엇인가요?

Supertest는 HTTP 서버 테스트를 위한 경량 Node.js 라이브러리입니다. Superagent를 기반으로 하며, 외부 클라이언트를 구동하지 않고도 상태 코드, 헤더, 응답 본문에 대해 표현력 있는 어설션을 작성할 수 있게 해줍니다. 다음과 같은 경우에 이상적입니다:

협업, API 규정 준수 거버넌스, 환경 오케스트레이션, 시각적 테스트가 필요할 때는 Supertest를 Apidog와 같은 API 테스트 플랫폼으로 보완할 수 있습니다. 이 기사의 나머지 부분에서는 이 두 가지를 모두 수행하는 방법을 보여줍니다.

button

Supertest 설치 및 설정

Supertest는 몇 분 안에 설치할 수 있습니다. npm, pnpm 또는 yarn을 사용하세요:

# npm   npm install --save-dev supertest jest

# pnpm  pnpm add -D supertest jest

# yarn

yarn add -D supertest jest

최소한의 Express API (app.js):

const express = require('express');

const app = express();



app.get('/greet', (req, res) => {

  const name = req.query.name || 'World';

  res.json({ message: `Hello, ${name}!` });

});



module.exports = app;

Supertest + Jest를 사용한 간단한 테스트 (app.test.js):

const request = require('supertest');

const app = require('./app');



describe('GET /greet', () => {

  it('greets anonymously', async () => {

    const res = await request(app)

      .get('/greet')

      .expect('Content-Type', /json/)

      .expect(200);



    expect(res.body.message).toBe('Hello, World!');

  });



  it('greets by name', async () => {

    const res = await request(app)

      .get('/greet?name=Alice')

      .expect('Content-Type', /json/)

      .expect(200);



    expect(res.body.message).toBe('Hello, Alice!');

  });

});

테스트 실행을 위해 package.json 업데이트:

{

  "scripts": {

    "test": "jest"

  }

}

테스트 실행:

npm test

Mocha나 Vitest를 선호하더라도 Supertest는 동일하게 작동합니다. .expect() API는 동일합니다.

훌륭한 Supertest 어설션 작성하기

Supertest의 강점은 연결 가능한 어설션에 있습니다. 작성하기 빠르고 읽기 쉽습니다. 매일 사용할 패턴은 다음과 같습니다:

request(app)

  .get('/users')

  .expect(200)

  .expect('Content-Type', /json/);
request(app)

  .get('/users')

  .expect(200)

  .expect(res => {

    if (!Array.isArray(res.body)) throw new Error('Expected an array');

    if (res.body.length === 0) throw new Error('Expected at least one user');

  });
request(app)

  .get('/health')

  .expect(200)

  .expect({ status: 'ok' });



request(app)

  .get('/health')

  .expect(200)

  .expect(/"status":"ok"/);
request(app)

  .post('/posts')

  .set('Authorization', 'Bearer test-token')

  .send({ title: 'Hello', body: 'World' })

  .expect(201)

  .expect(res => {

    if (!res.body.id) throw new Error('Missing id');

  });
const agent = request.agent(app);

await agent.get('/login').expect(200);

await agent.get('/me').expect(200).expect(res => {

  if (!res.body.user) throw new Error('Expected authenticated user');

});
팁: 테스트를 작고 확정적으로 유지하세요. Supertest는 컨트롤러, 미들웨어 및 어댑터를 독립적으로 검증하는 데 탁월합니다.

CI/CD 및 모노레포에서의 Supertest

일관된 품질을 유지하기 위해 모든 풀 리퀘스트에 대해 CI에서 Supertest를 실행합니다. 일반적인 설정:

GitHub Actions 스니펫 예시:

name: api-tests

on: [push, pull_request]

jobs:

  test:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: '20'

      - run: npm ci

      - run: npm test -- --ci

모노레포에서는 영향을 받는 테스트만 실행하고 node_modules를 캐시하여 피드백 루프 속도를 높입니다. Supertest의 최소한의 오버헤드는 대규모 코드베이스에 매우 적합합니다.

API 테스트 플랫폼을 사용해야 할 때

Supertest는 빠르고 코드 수준의 피드백에 탁월합니다. 그러나 프로덕션 현실은 더 많은 것을 요구합니다:

이것이 Apidog와 같은 API 테스트 플랫폼이 빛을 발하는 지점입니다. Apidog는 API 설계, 모의(mocking), 테스트, 디버깅, 문서화를 통합하여 팀을 정렬하고 품질 게이트를 견고하게 유지합니다.

button
Apidog Testing UI

Apidog가 Supertest를 보완하는 이유

결합된 워크플로: Supertest + Apidog

개발자 중심의 검사에는 Supertest를 사용하고, 엔드투엔드 협업에는 Apidog를 사용하세요. 다음은 실용적인 책임 분담입니다:

작업
Supertest
Apidog
컨트롤러/미들웨어 단위 검사
탁월함
보완적
빠른 계약 회귀 (상태/헤더)
탁월함
탁월함
스키마 거버넌스 (OpenAPI)
수동
최고 수준
프론트엔드용 모의 서버
제한적
내장
데이터 기반 시나리오
제한적
최고 수준
환경 전반의 CI 오케스트레이션
좋음
최고 수준
팀 협업/문서
최소
최고 수준

예시 흐름:

고급 Supertest 패턴

성과를 내는 몇 가지 추가 팁:

결론: API 품질에 대한 균형 잡힌 접근 방식

품질 높은 API는 속도와 엄격함 모두를 갖춰 구축됩니다. Supertest는 개발자에게 코드에 가까운 엔드포인트를 빠르고 표현력 있게 검증하는 방법을 제공합니다. 이는 빠른 피드백 루프와 브랜치를 벗어나기 전에 회귀를 잡아내는 데 완벽합니다. 간단하고 신뢰할 수 있으며, 많은 Node.js 백엔드에서 검증되었습니다.

그러나 시스템이 성장함에 따라 협업, 계약 거버넌스, 환경 인지 실행이 필요합니다. 이때 통합 API 테스트 플랫폼인 Apidog가 워크플로를 향상시킵니다. 계약 설계(OpenAPI), 모의 서버, 시각적 어설션, 환경 변수, CI 오케스트레이션을 통합함으로써 Apidog는 팀이 아이디어부터 배포까지 일사불란하게 움직이도록 돕습니다. 프론트엔드, 백엔드, QA는 동일한 진실의 원천을 공유할 수 있으며, Supertest는 빠르고 확정적인 어설션으로 코드 경로를 계속 보호합니다.

확신 있는 속도를 원한다면 둘 다 사용하세요:

이 균형 잡힌 접근 방식은 오늘날뿐만 아니라 제품이 진화함에 따라 견고한 API를 만들어냅니다. 지금 바로 Supertest 검사를 작성하고, Apidog와 함께 프로덕션 수준의 파이프라인에서 생명을 불어넣으세요.

button

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드