UserRestController에 대한 문서화 테스트를 작성한다.

[woowahan-pjs]

2일

[SuyeonChoi]

🚀 트러블 슈팅

1. RestController 테스트에서의 일관성?

• 상황
  • 테스트에서 mockMvc.post()와 mockMvc.perform()가 혼용되고 있다.
  • 그러나, restdocs가 적용돼있는 (andDo()가 사용되고 있는) 코드에서는 mockMvc.perform()만 사용되고 있다.
    • 왜 mockMvc.post() DSL과 restdocs 문법을 같이 사용하는 코드는 없을까?
• 증상
  • mockMvc.post()와 같이 DSL(중괄호)을 사용하여 테스트를 실행했을 때, 테스트는 성공하지만 build/generated-snippets폴더에 스니펫이 생성이 되지 않음.
  • mockMvc.perform()을 사용하여 소괄호를 사용하여 테스트를 실행했을 때엔 테스트도 통과하고, 스니펫도 생성이 됨.
• 해결 방법
  • 코틀린 DSL과 RestDocs를 함께 사용하기 위해서는 andDo { handle(document("home")) } 과 같이 handle을 추가해야한다. 하지만 이렇게까지 코틀린 DSL을 사용해야하는지 고민됨🤔
  • 코틀린 DSL을 최대한 활용하기 위해 handle을 사용하는 방식을 적용하기로 함

2. 테스트 코드 MockMvc(RestDocs) 설정

• 상황
  • 초기 코드에서는 @Import(RestDocsConfiguration::class) 와 @BeforeEach 두 방식이 같이 혼재되어 있다.
• 증상
  • RestDocs 테스트 setting 시 설정 방식은 두가지 방법으로 나눠진다.
    1. @AutoConfigureRestDocs 로 초기 세팅을 하고 @Import(RestDocsConfiguration::class) 을 적용해서 커스텀하는 방식
    2. @BeforeEach 에서 초기 세팅과 커스텀을 동시에 하는 방식
• 해결 방법
  • 2번 방법으로 통일해서 적용하기로 결정했다.

3. 예외에 대한 문서화

• 상황
  • 예외에 대한 문서화를 하는 방법에 대한 레퍼런스가 부족함.
• 증상
  • (성공 케이스처럼) 스니펫을 생성해보았지만 결과적으로 생성된 스니펫 response-body에 원하는 예외 메세지가 아닌 null이 보여짐

• 해결 방법
  • mocking 시 예외 클래스와 해당하는 예외 메세지를 담아줘서 해결
  • 우리와 같은 고민
  • 참고

4. Request Parameters를 받는 경우

• 증상
  • requestParam인 경우에는 현재 지원플랫폼 코드에서는 pathParameters를 사용하고 있다. 그러나, RestDocs에서 pathParameters를 이용하여 테스트를 실행했을 때, urlTemplate not found. If you are using MockMvc did you use RestDocumentationRequestBuilders to build the request? 에러가 발생하며 실패한다.
• 해결방법
  • pathParameters 대신 requestParameters를 사용한다. 이는 공식문서에서도 사용되고 있는 방법이다.
  • 공식문서

5. @ 인코딩 오류

• 증상
  • 이메일 형식으로 요청 시, RestDocs에서 이메일은 인코딩이 실패
• 원인 (22.07.16. 추가)
  • contentType을 지정해놓지 않으면 한글, 특수문자 등이 깨져서 나올 수 있음. body로 넣는 테스트 메서드들은 모두 contentType을 지정해주었지만, query param으로 요청에 넣는 메서드들은 contentType을 지정해주지 않은 것이 문제.
• 해결방법
  • 아래와 같이 지정해줌.

    mockMvc.post("/api/users/authenticate-email") {
        param("email", userRequest.email)
        param("authenticationCode", "code")
        contentType = MediaType.APPLICATION_JSON  // 추가된 부분
    }.
    // ...

깨달은 점

RestDocs의 request와 resposone에서 객체와 리스트 처리하기

리스트나 객체를 .andWithPrefix로 indent 생성 시,

• 리스트인 경우에는 andWithPrefix에서 body.[].를 prefix로 리스트 데이터를 삽입

  responseFields(
          fieldWithPath("message").description("응답 메시지"),
          fieldWithPath("body.[]").description("모집 목록"),
      ).andWithPrefix("body.[].", RECRUITMENT_FIELD_DESCRIPTORS)

• 리스트가 아닌 객체인 경우에는 andWithPrefix에서 body.를 prefix로 객체 데이터를 삽입(하단 코드 참고)

   PayloadDocumentation.responseFields(
               PayloadDocumentation.fieldWithPath("message").type(JsonFieldType.STRING).description("메시지"),
               PayloadDocumentation.fieldWithPath("body").type(JsonFieldType.OBJECT).description("유저정보")
       ).andWithPrefix("body.",
               PayloadDocumentation.fieldWithPath("id").type(JsonFieldType.NUMBER).description("아이디"),
               PayloadDocumentation.fieldWithPath("name").type(JsonFieldType.STRING).description("이름"),
               PayloadDocumentation.fieldWithPath("email").type(JsonFieldType.STRING).description("이메일"),
               PayloadDocumentation.fieldWithPath("phoneNumber").type(JsonFieldType.STRING).description("전화번호"),
               PayloadDocumentation.fieldWithPath("gender").type(JsonFieldType.STRING).description("성별"),
               PayloadDocumentation.fieldWithPath("birthday").type(JsonFieldType.STRING).description("생년월일")
       )