테스트 러너와 통합

여러분의 프로젝트에서는 일반적으로 Jest나 Mocha 같은 테스트 러너를 사용하고 있을 것입니다. quick-start 가이드에서 설명한 것처럼 테스트를 작성한 후, 사용 중인 테스트 프레임워크를 실행하면, 그 테스트 러너가 itdoc 테스트 코드(describeAPI(), itdoc() 등)를 자동으로 감지하고 실행하게 됩니다.

이 과정에서 itdoc은 여러분이 작성한 테스트 코드 내의 API 요청과 응답을 추출하여 문서를 생성합니다.

✅ 중요한 점

테스트를 실행할 때, 테스트 러너가 itdoc 테스트 코드가 위치한 파일을 포함하는 경로를 대상으로 실행되어야 합니다. 해당 경로가 포함되지 않으면, 테스트 러너는 itdoc 테스트 코드를 감지하지 못합니다.

따라서 package.json의 test 스크립트에는 itdoc 테스트 코드가 포함된 경로를 명시해야 합니다.

Jest

{
    "scripts": {
        "test": "jest ."
    }
}

Mocha

{
    "scripts": {
        "test": "mocha ."
    }
}

상세한 설정 방법은 각 테스트 러너의 공식 문서를 참조하세요.

테스트 사전 설정 및 후처리

테스트 전/후 처리 작업을 수행하고 싶다면, 각 테스트 러너에서 제공하는 훅을 그대로 사용하시면 됩니다.

예를 들어, Jest에서는 beforeAll, afterAll 같은 훅을 사용하여 테스트 전후에 작업을 수행할 수 있습니다.

describeAPI(
    HttpMethod.POST,
    "/signup",
    {
        summary: "User Registration API",
        tag: "Auth",
        description: "Registers a new user with username and password.",
    },
    app,
    (apiDoc) => {

        beforeEach(() => { // Jest에서 제공하는 훅
            console.log("before each")
        })

        itDoc("Successful registration", () => {
            return apiDoc
                .test()
                .req()
                .body({
                    username: field("Username", "testuser"),
                    password: field("Password", "Password123!"),
                })
                .res()
                .status(HttpStatus.CREATED)
                .body({
                    message: field("Success message", "User created successfully"),
                })
        })
})

afterAll(() => { // Jest에서 제공하는 훅
    console.log("afterAll")
})

모킹 사용 예시

itdoc는 Jest와 Mocha에서 사용할 수 있는 다양한 모킹 라이브러리와 함께 사용할 수 있습니다. 하지만 itdoc은 신뢰성있는 API 문서를 생성하기 위해 최소한의 모킹만을 권장합니다. 아래는 API 응답에서 시간 정보를 모킹하는 예시입니다.

import * as MockDate from "mockdate"

describeAPI(
  HttpMethod.POST,
  "/api/v1/users/login",
  {
    summary: "User Login API",
    tag: "Auth",
    description: "사용자 로그인 API",
  },
  app,
  (apiDoc) => {
    let mockedDate = new Date("2023-10-01T00:00:00Z")

    beforeEach(() => {
      MockDate.set(mockedDate) // 실제 모킹
    })

    afterEach(() => {
      MockDate.reset() // 모킹 해제
    });

    itDoc("존재하는 아이디와 패스워드를 입력하면 로그인에 성공한다.", () => {
      return apiDoc
        .test()
        .prettyPrint()
        .req()
        .body({
          username: field("username", "penek"),
          password: field("password", "penek"),
        })
        .res()
        .status(HttpStatus.OK)
        .body({
          "detail" : {
            "token" : field("생성된 JWT 토큰", (val) => {
              assertJWT(val, "penek");
            }),
            "expire" : field("토큰 만료일", mockedDate.toISOString()) // 모킹된 시간 정보로 검증
          }
        })
    })
})