[Testing] TDD/ API 문서화

📌 개인적인 공간으로 공부를 기록하고 복습하기 위해 사용하는 블로그입니다.
정확하지 않은 정보가 있을 수 있으니 참고바랍니다 :😸
[틀린 내용은 댓글로 남겨주시면 복받으실거에요]

TDD(Test Driven Development, 테스트 주도개발)

TDD의 개념을 한마디로 요약하자면 ‘테스트를 먼저 하고 구현은 그다음에 한다’이다.

TDD는 모든 작업 이전에 테스트를 먼저한다.

1. 이해 당사자들 간에 수집된 요구 사항과 설계된 화면(UI 설계서 등) 등을 기반으로 도메인 모델을 도출합니다.
2. 도출된 도메인 모델을 통해 클라이언트의 요청을 받아들이는 엔드포인트와 비즈니스 로직, 데이터 액세스를 위한 클래스와 인터페이스 등을 설계해서 큰 그림을 그려봅니다.
3. 클래스 설계를 통해 애플리케이션에 대한 큰 그림을 그려보았다면 클래스와 인터페이스의 큰 틀을 작성합니다.
4. 클래스와 인터페이스의 큰 틀이 작성되었다면 클래스와 인터페이스 내에 메서드를 정의하면서 세부 동작을 고민하고, 코드로 구현합니다.
5. 해당 메서드의 기능 구현이 끝났다면 구현한 기능이 잘 동작하는지 테스트합니다.
6. 테스트에 문제가 발생한다면 구현한 코드를 디버깅하면서 문제의 원인을 찾습니다.

✔️ TDD 관점에서 두드러지는 점 한 가지는 3번 ~ 6번의 과정에서 구현이 먼저고, 테스트가 나중이라는 점

✔️ TDD를 잘했을 때는 6번이 줄어들긴 하는데 해외에서도 그렇고 복잡도만 올라가지 크게 장점이 없어서 사용을 하지 않는 추세라고 함.

⭐ TDD의 개발 방식은 ‘실패하는 테스트 → 실패하는 테스트를 성공할 만큼의 기능 구현 → 성공하는 테스트 → 리팩토링 → 실패하는 테스트와 성공하는 테스트 확인’이라는 흐름을 반복한다.

TDD의 특징 정리

• TDD는 모든 조건에 만족하는 테스트를 먼저 진행한 뒤에 조건에 만족하지 않는 테스트를 단계적으로 진행하면서 실패하는 테스트를 점진적으로 성공시킨다.
• TDD는 테스트 실행 결과가 “failed”인 테스트 케이스를 지속적으로 그리고 단계적으로 수정하면서 테스트 케이스 실행 결과가 “passed”가 되도록 만들고 있습니다.
• TDD는 테스트가 “passed” 될 만큼의 코드만 우선 작성한다.
• TDD는 ‘실패하는 테스트 → 실패하는 테스트를 성공할 만큼의 기능 구현 → 성공하는 테스트 → 리팩토링 → 실패하는 테스트와 성공하는 테스트 확인’이라는 흐름을 반복

앞에서 TDD 방식으로 진행한 패스워드 유효성 검증 기능의 구현에 대한 설명 자체는 길지만 실제 TDD 방식으로 잘 진행된다면 테스트와 기능 구현, 리팩토링까지 빠르게 진행이 가능.

API 문서화

• API 문서화란 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야 되는 요청 정보(요청 URL(또는 URI), request body, query parameter 등)를 문서로 잘 정리하는 것을 의미
• REST API 기반의 백엔드 애플리케이션을 클라이언트 쪽에서 사용하려면 API 사용을 위한 어떤 정보가 필요함 → API 사용을 위한 어떤 정보가 담겨 있는 문서를 API 문서 또는 API 스펙(사양, Specification)
• 개발이 들어가기전에 문서가 나와야 함 → 기획단계에서 설계를 함.

Spring Rest Docs vs Swagger

Swagger

1. 특징
   • 애너테이션 기반의 API 문서화 방
   • 애플리케이션 코드에 문서화를 위한 애너테이션들이 포함된다.
   • API 문서와 API 코드 간의 정보 불일치 문제가 발생할 수 있다.
   • API 툴로써의 기능을 활용할 수 있다.
   • 문서화 뿐만 아니라 테스트 툴의 기능 있고 UI가 깔끔해서 문서를 통해 확인하기 좋음.
   • BUT, 기능별 분리가 안되고 가독성 및 유지 보수성이 떨어진다.
   • 배포시점에 코드가 들어가게 된다. → 주석과 로그를 포함시키지 않는 것이 일반적인데 배포할때는 문서가 필요없는데 일일이 벗겨내야한다.
2. 예제

   1. Controller → 무수히 많은 애너테이션

       @ApiOperation(value = "회원 정보 API", tags = {"Member Controller"}) // (1)
       @RestController
       @RequestMapping("/v11/swagger/members")
       @Validated
       @Slf4j
       public class MemberControllerSwaggerExample {
           private final MemberService memberService;
           private final MemberMapper mapper;
              
           public MemberControllerSwaggerExample(MemberService memberService, MemberMapper mapper) {
               this.memberService = memberService;
               this.mapper = mapper;
           }
              
           // (2)
           @ApiOperation(value = "회원 정보 등록", notes = "회원 정보를 등록합니다.")
              
           // (3)
           @ApiResponses(value = {
                   @ApiResponse(code = 201, message = "회원 등록 완료"),
                   @ApiResponse(code = 404, message = "Member not found")
           })
           @PostMapping
           public ResponseEntity postMember(@Valid @RequestBody MemberDto.Post memberDto) {
               Member member = mapper.memberPostToMember(memberDto);
               member.setStamp(new Stamp()); // homework solution 추가
              
               Member createdMember = memberService.createMember(member);
              
               return new ResponseEntity<>(
                       new SingleResponseDto<>(mapper.memberToMemberResponse(createdMember)),
                       HttpStatus.CREATED);
           }
              
           ...
           ...
              
           // (4)
           @ApiOperation(value = "회원 정보 조회", notes = "회원 식별자(memberId)에 해당하는 회원을 조회합니다.")
           @GetMapping("/{member-id}")
           public ResponseEntity getMember(
                   @ApiParam(name = "member-id", value = "회원 식별자", example = "1")  // (5)
                   @PathVariable("member-id") @Positive long memberId) {
               Member member = memberService.findMember(memberId);
               return new ResponseEntity<>(
                       new SingleResponseDto<>(mapper.memberToMemberResponse(member))
                                           , HttpStatus.OK);
           }
              
           ...
           ...
       }
              
      

   2. DTO, Request Body나 Response Body 같은 DTO 클래스에도 아래의 코드와 같이 Swagger의 애너테이션을 일일이 추가해 주어야 함.

       @ApiModel("Member Post")  // (1)
       @Getter
       public class MemberPostDto {
           // (2)
           @ApiModelProperty(notes = "회원 이메일", example = "hgd@gmail.com", required = true)
           @NotBlank
           @Email
           private String email;
              
           // (3)
           @ApiModelProperty(notes = "회원 이름", example = "홍길동", required = true)
           @NotBlank(message = "이름은 공백이 아니어야 합니다.")
           private String name;
              
           // (4)
           @ApiModelProperty(notes = "회원 휴대폰 번호", example = "010-1111-1111", required = true)
           @Pattern(regexp = "^010-\\\\d{3,4}-\\\\d{4}$",
                   message = "휴대폰 번호는 010으로 시작하는 11자리 숫자와 '-'로 구성되어야 합니다.")
           private String phone;
       }
              
      

3. Swagger API 문서 화면 예

   Postman에서 MemberControlle에 HTTP 요청을 전송하듯이 [Execute] 버튼을 누르면 MemberController에 요청을 전송가능

   

Spring Rest Docs

1. 특징
   • 테스트 코드 기반의 API 문서화 방식
   • 애플리케이션 코드에 문서화를 위한 정보들이 포함되지 않는다.
   • 테스트 케이스의 실행이 “passed”여야 API 문서가 생성된다.
   • 테스트 케이스를 반드시 작성해야 된다.
   • API 툴로써의 기능은 제공하지 않는다.

2. 예제

   

   • 코드의 노란 박스부분이 문서화 관련코드이다.
   • 테스트 코드 검증에 문서화 코드에 포함되어 있음.→ 그렇게 때문에 문서화하려면 테스트 코드가 필수

3. Spring Rest Docs의 API 문서화면 예

   

Spring Rest Docs

Spring Rest Docs의 API 문서 생성 흐름

1. 테스트 코드 작성
   1. 슬라이스 테스트 코드 작성 ⅰ. Spring Rest Docs는 Controller의 슬라이스 테스트와 밀접한 관련이 있음
   2. API 스펙 정보 코드 작성 ⅰ. 슬라이스 테스트 코드 다음에 Controller에 정의되어 있는 API 스펙 정보(Request Body, Response Body, Query Parameter 등)를 코드로 작성
2. test 태스크(task) 실행
   1. 작성된 슬라이스 테스트 코드를 실행한다. ⅰ. 하나의 테스트 클래스를 실행시켜도 되지만 일반적으로 Gradle의 빌드 태스크(task)중 하나인 test task를 실행시켜서 API 문서 스니펫(snippet)을 일괄 생성한다.
   2. 테스트 실행 결과가 “passed”이면 다음 작업을 진행하고, “failed”이면 문제를 해결하기 위해 테스트 케이스를 수정한 후, 다시 테스트를 진행해야 한다. →테스트를 통과해야 문서 작업 가능.
3. API 문서 스니펫( .adoc 파일) 생성
   1. 테스트 케이스의 테스트 실행 결과가 “passed”이면 테스트 코드에 포함된 API 스펙 정보 코드를 기반으로 API 문서 스니펫이 .adoc 확장자를 가진 파일로 생성된다.

스니펫이란? 스니펫은 테스트 케이스 하나당 하나의 스니펫이 생성되며, 여러 개의 스니펫을 모아서 하나의 API 문서를 생성 가능하다. API 문서 생성

1. 생성된 API 문서 스니펫을 모아서 하나의 API 문서로 생성합니다.
2. API 문서를 HTML로 변환
   1. 생성된 API 문서를 HTML 파일로 변환합니다.
   2. HTML로 변환된 API 문서는 HTML 파일 자체를 공유할 수도 있고, URL을 통해 해당 HTML에 접속해서 확인할 수 있다.

Spring Rest Docs 설정

1. build.gradle 설정

    plugins {
    	id 'org.springframework.boot' version '2.7.1'
    	id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    	id "org.asciidoctor.jvm.convert" version "3.3.2"    // (1)
    	id 'java'
    }
       
    /*
       
     (1) .adoc 파일 확장자를 가지는 AsciiDoc 문서를 생성해 주는
     Asciidoctor를 사용하기 위한 플러그인을 추가
       
    */
       
    group = 'com.springboot'
    version = '0.0.1-SNAPSHOT'
    sourceCompatibility = '11'
       
    repositories {
    	mavenCentral()
    }
       
    ext { // (2) ext 변수의 set() 메서드를 이용해서 API 문서 스니펫이 생성될 경로를 지정
    	set('snippetsDir', file("build/generated-snippets"))
    }
       
    /* 
    (3)
    AsciiDoctor에서 사용되는 의존 그룹을 지정:asciidoctor task가 실행되면 
    내부적으로 (3)에서 지정한 ‘asciidoctorExtensions’라는 그룹을 지정
    */
       
    configurations {
    	asciidoctorExtensions
    }
       
    dependencies {
            /* (4) org.springframework.restdocs:spring-restdocs-mockmvc'를 추가함으로써 
            spring-restdocs-core와 spring-restdocs-mockmvc 의존 라이브러리가 추가된다.*/
       	
    	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
       
            /*(5)
            pring-restdocs-asciidoctor 의존 라이브러리를 추가
            (3)에서 지정한 asciidoctorExtensions 그룹에 의존 라이브러리가 포함된다
            */
    	asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
       
    	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    	implementation 'org.springframework.boot:spring-boot-starter-validation'
    	implementation 'org.springframework.boot:spring-boot-starter-web'
    	compileOnly 'org.projectlombok:lombok'
    	runtimeOnly 'com.h2database:h2'
    	annotationProcessor 'org.projectlombok:lombok'
    	testImplementation 'org.springframework.boot:spring-boot-starter-test'
    	implementation 'org.mapstruct:mapstruct:1.5.1.Final'
    	annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.1.Final'
    	implementation 'org.springframework.boot:spring-boot-starter-mail'
       
    	implementation 'com.google.code.gson:gson'
    }
       
    // (6) :test task 실행 시, API 문서 생성 스니펫 디렉토리 경로를 설정
    tasks.named('test') {
    	outputs.dir snippetsDir
    	useJUnitPlatform()
    }
       
    /* (7) sciidoctor task 실행 시, Asciidoctor 기능을 사용하기 위해 
    :asciidoctor task에 asciidoctorExtensions을 설정*/
       
    tasks.named('asciidoctor') {
    	configurations "asciidoctorExtensions"
    	inputs.dir snippetsDir
    	dependsOn test
    }
       
    /* (8) :build task 실행 전에 실행되는 task
    :copyDocument task가 수행되면 index.html 파일이 
    src/main/resources/static/docs 에 copy 되며, 
    copy 된 index.html 파일은 API 문서를 파일 형태로 외부에 제공하기 위한 용도로 사용*/
       
    task copyDocument(type: Copy) {
    	dependsOn asciidoctor            
    		// (8-1) :asciidoctor task가 실행된 후에 task가 실행되도록 의존성을 설정
    	from file("${asciidoctor.outputDir}")   
    		// (8-2) build/docs/asciidoc/" 경로에 생성되는 index.html을 copy
    	into file("src/main/resources/static/docs")   
    		// (8-3) src/main/resources/static/docs" 경로로 index.html을 추가
    }
       
    build {
    	dependsOn copyDocument  
    		// (9):build task가 실행되기 전에 :copyDocument task가 먼저 수행되도록 함.
    }
       
    // (10)  애플리케이션 실행 파일이 생성하는 :bootJar task 설정
    bootJar {
    	dependsOn copyDocument    
    		// (10-1)  :bootJar task 실행 전에 :copyDocument task가 실행되도록 의존성을 설정
    	from ("${asciidoctor.outputDir}") { 
    		into 'static/docs'    
    		 /*(10-2) Asciidoctor 실행으로 생성되는 index.html 파일을 jar 파일 안에 추가
    		 jar 파일에 index.html을 추가해 줌으로써 웹 브라우저에서 접속
    		 (http://localhost:8080/docs/index.html) 후, API 문서를 확인 할 수 있다.*/
    	}
    }
       
   

2. API 문서 스니펫을 사용하기 위한 템플릿 API 문서 생성

   • Gradle 기반 프로젝트에서는 아래 경로에 해당하는 디렉토리를 생성해 주어야 합니다.
     • src/docs/asciidoc/
   • 다음으로 src/docs/asciidoc/ 디렉토리 내에 비어있는 템플릿 문서(index.adoc)를 생성해 주면 된다.

슬라이스테스트

1. MemberController가 요청을 잘 전달받고, 응답을 잘 전송하며 요청과 응답이 정상적으로 수행되면 API 문서 스펙 정보를 잘 읽어 들여서 적절한 문서를 잘 생성하느냐 하는 것을 Test하면 됨
2. MemberService와 MemberMapper의 메서드를 호출하지 않도록 관계를 단절 ⇒ MemberService와 MemberMapper의 Mock Bean을 주입

1️⃣ 애너테이션

1. @WebMvcTest 애너테이션은 Controller를 테스트하기 위한 전용 애너테이션, 괄호 안에는 테스트 대상 Controller 클래스를 지정
2. @MockBean(JpaMetamodelMappingContext.class)

@SpringBootTest vs @WebMvcTest

기존에는@SpringBootTest + @AutoConfigureMockMvc 애너테이션으로 Controller의 테스트를 진행

@SpringBootTest와 @WebMvcTest의 차이점은? 먼저 @SpringBootTest 애너테이션은 @AutoConfigureMockMvc과 함께 사용되어 Controller를 테스트할 수 있는데, 프로젝트에서 사용하는 전체 Bean을 ApplicationContext에 등록하여 사용한다. 한마디로 테스트 환경을 구성하는 것은 편리하긴 한데 실행 속도가 상대적으로 느림.

@WebMvcTest 애너테이션의 경우 Controller 테스트에 필요한 Bean만 ApplicationContext에 등록하기 때문에 실행 속도는 상대적으로 빠르다.

다만, Controller에서 의존하고 있는 객체가 있다면 해당 객체에 대해서 Mock 객체를 사용하여 의존성을 일일이 제거해 주어야 합니다.

결과적으로 @SpringBootTest는 데이터베이스까지 요청 프로세스가 이어지는 통합 테스트에 주로 사용되고, @WebMvcTest는 Controller를 위한 슬라이스 테스트에 주로 사용한다.

2️⃣ MemberController의 postMember() 핸들러 메서드에 대한 API 스펙정보 추가

1. 노란박스 내의 document(…) 메서드는 API 스펙 정보를 전달받아서 실질적인 문서화 작업을 수행하는 RestDocumentationResultHandler 클래스에서 가장 핵심 기능을 하는 메서드
2. document() 메서드의 첫 번째 파라미터는 API 문서 스니펫의 식별자 역할을 하며, “post-member”로 지정했기 때문에 문서 스니펫은 post-member 디렉토리 하위에 생성된다.

3. getRequestPreProcessor() 와 getResponsePreProcessor()

   문서 스니펫을 생성하기 전에 request와 response에 해당하는 문서 영역을 전처리하는 역할을 하는데 아래와 같이 공통화한 후, 모든 테스트 케이스에서 재사용할 수 있게 함

    package com.springboot.util;
       
    import org.springframework.restdocs.operation.preprocess.OperationRequestPreprocessor;
    import org.springframework.restdocs.operation.preprocess.OperationResponsePreprocessor;
       
    import static org.springframework.restdocs.operation.preprocess.Preprocessors.*;
       
    public interface ApiDocumentUtils {
       static OperationRequestPreprocessor getRequestPreProcessor() {
           return preprocessRequest(prettyPrint());
        }
       
        static OperationResponsePreprocessor getResponsePreProcessor() {
            return preprocessResponse(prettyPrint());
        }
    }
       
   

4. requestFields(…)는 문서로 표현될 request body를 의미, List<FieldDescriptor>의 원소인 FieldDescriptor 객체가 request body에 포함된 데이터를 표현
5. responseHeaders(…)는 문서로 표현될 response header를 의미,파라미터로 전달되는 HeaderDescriptor 객체가 response header를 표현
6. 실행 결과가 “passed”이면 우리가 작성한 API 스펙 정보를 기반으로 문서 스니펫이 만들어짐.

3️⃣ MemberController의 patchMember() 핸들러 메서드에 대한 API 스펙정보 추가

1. memberId의 경우, path variable 정보로 memberId를 전달받기 때문에 MemberDto.Patch DTO 클래스에서 request body에 매핑되지 않는 정보 ⇒ 그래서 (2)와 같이 ignored()를 추가해서 API 스펙 정보에서 제외
2. 회원정보는 선택적으로 수정해야 하므로 optional()을 추가하여 선택정보로 설정함.

---

Spring 카테고리 내 다른 글 보러가기