Express 외 테스트방법

이 문서는 Express가 아닌 다른 웹 프레임워크에서 itdoc을 사용하는 방법을 안내합니다.

NestJS 예제

NestJS는 내부적으로 Express를 사용하지만, Nest의 구조상 describeAPI에 전달할 Express 타입의 app 인스턴스를 직접 생성해주어야 합니다. 아래 예시는 가장 널리 쓰이는 Jest 테스트 러너 기준이며, 다른 러너를 사용하신다면 각 러너의 문서에 따라 동일한 개념으로 설정해 주세요.

---

1. globalSetup 작성

Jest globalSetup을 이용해 테스트 전용 Nest 애플리케이션을 한 번만 기동하고, 모든 테스트에서 재사용합니다.

test/global-setup.ts :

import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import { AppModule } from '../src/app.module';
import type { App } from 'supertest/types';

declare global {
  // itdoc에서 사용할 supertest 핸들을 전역으로 노출
  var __APP__: App;
}

export default async function globalSetup(): Promise<void> {
  const moduleFixture: TestingModule = await Test.createTestingModule({
    imports: [AppModule],
  }).compile();

  const app: INestApplication = moduleFixture.createNestApplication();
  await app.init();

  global.__APP__ = app.getHttpServer() as App;
}

---

2. Jest 설정에 globalSetup 등록

jest-e2e.json(또는 사용 중인 Jest 설정 파일)에 다음 항목을 추가합니다.

{
  "globalSetup": "<rootDir>/test/global-setup.ts"
}

---

3. 테스트 코드에서 itdoc 사용

itdoc의 app 인자로 global.__APP__ 을 전달하면 끝입니다.

import { describeAPI, field, HttpMethod, HttpStatus, itDoc } from 'itdoc';

describeAPI(
  HttpMethod.GET,
  '/',
  {
    summary: 'Hello World',
    description: 'Returns greeting message',
    tag: 'hello',
  },
  global.__APP__, // ← globalSetup에서 전역으로 노출한 핸들
  // ...후략
);

Fastify 예제

Fastify 환경에서 itdoc을 사용하려면 describeAPI에 전달할 Express 호환 핸들(app 인스턴스)을 생성해주어야 합니다. NestJS 예제와 유사하지만 Fastify만의 초기화 방식에 맞게 설정해야 합니다.

아래 예시는 가장 널리 사용되는 Jest 테스트 러너 기준이며, 다른 러너를 사용할 경우 해당 러너의 문서를 참고하여 동일한 개념으로 적용하시면 됩니다.

---

1. globalSetup 작성

Jest globalSetup을 사용해 테스트 전용 Fastify 애플리케이션을 한 번만 초기화하고 모든 테스트에서 공유합니다.

test/global-setup.js :

const buildFastify = require("../src/app")

async function globalSetup() {
    const fastify = buildFastify()
    await fastify.ready()

    global.__APP__ = fastify.server
}

module.exports = globalSetup

2. Jest 설정에 globalSetup 등록

jest.config.js 또는 별도의 설정 파일에 다음을 추가합니다:

module.exports = {
  globalSetup: '<rootDir>/test/global-setup.js',
  // 기타 Jest 설정 옵션...
};

---

3. 테스트 코드에서 itdoc 사용

itdoc의 app 인자에 global.__APP__ 을 전달합니다.

import { describeAPI, field, HttpMethod, HttpStatus, itDoc } from 'itdoc';

describeAPI(
  HttpMethod.GET,
  '/hello',
  {
    summary: 'Hello World API',
    description: '인사 메시지를 반환합니다',
    tag: 'hello',
  },
  global.__APP__,
  (apiDoc) => {
    itDoc('Hello World를 반환해야 합니다', () => {
      return apiDoc
        .test()
        .req()
        .res()
        .status(HttpStatus.OK)
        .body({
          message: field('인사 메시지', 'Hello World!'),
        });
    });
  },
);