Rest Assured와 Rest Docs를 통한 테스트 및 API문서화

🐳 인수 테스트(Acceptance Test)란? 🐳

인수 테스트(acceptance test)는 시스템이 예상대로 동작하는지 확인하고, 요구 사항에 맞는지 확신하기 위해 하는 테스트이다.
시스템을 인수하기 전 요구 분석 명세서에 명시된 대로 모두 충족시키는지를 사용자가 테스트한다.
인수 테스트는 사용자 주도로 이루어지며, 오류 발견보다는 제품의 출시 여부를 판단하는 것이 주목적이다
백엔드 개발에서 UI 레벨에서 인수 테스트를 하는건 무리가 있기 때문에 API레벨에서 사용자 시나리오를 만족시키기 위해 테스트한다.

📌 REST Assured vs MockMvc

Mock는 서블릿 컨테이너의 구동 없이, 시뮬레이션된 MVC 환경에서 모의 HTTP 서블릿 요청을 전송하는 기능을 제공하는 유틸리티 클래스이다. 주로 Controller 레이어의 단위 테스트에 쓰인다.

REST Assured는 REST API를 검증하기 위한 라이브러리이며 End to End Test이다.
시스템 전체 레이어를 관통하며 사용자 관점에서 기능이 잘 동작하는지 테스트할 수 있다.

인수테스트를 하는데 목을 사용하는건 어울리지 않는다. 통합적인 관점에서 오류를 찾을 수 있는 REST Assured를 사용하는게 어울린다.

📌 시작

간단한 회원가입과 로그인 API를 테스트 해보겠습니다.

회원가입

• 학생증 사진을 받습니다.
• 아이디와 패스워드, 학번을 받습니다.

로그인

• 아이디와 패스워드를 받습니다.

📌 의존성 주입

plugins {
	id 'java'
	id 'org.springframework.boot' version '2.7.11'
	id 'io.spring.dependency-management' version '1.0.15.RELEASE'
	id 'com.ewerk.gradle.plugins.querydsl' version '1.0.10'

	//rest docs
	id "org.asciidoctor.jvm.convert" version "3.3.2"
}

group = 'cbnu.io'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

configurations {
	asciidoctorExt
	compileOnly {
		extendsFrom annotationProcessor
	}
}

repositories {
	mavenCentral()
}

ext {
	asciidocVersion = "2.0.6.RELEASE"
	snippetsDir = file('build/generated-snippets')
}


dependencies {
	...

	// Test
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	asciidoctorExt "org.springframework.restdocs:spring-restdocs-asciidoctor:${asciidocVersion}"
	testImplementation 'org.springframework.security:spring-security-test'
	testImplementation "org.springframework.restdocs:spring-restdocs-mockmvc:${asciidocVersion}"
	testImplementation 'org.springframework.restdocs:spring-restdocs-restassured'
	testImplementation 'io.rest-assured:rest-assured'
	testImplementation 'org.junit.jupiter:junit-jupiter-api:5.9.2'
	testImplementation 'org.junit.jupiter:junit-jupiter-engine:5.9.2'
	...
}

tasks.named('test') {
	outputs.dir snippetsDir
	useJUnitPlatform()
}

//-------------------rest docs----------------------------------------------
test {
	outputs.dir snippetsDir
}

asciidoctor {
	inputs.dir snippetsDir
	configurations 'asciidoctorExt'
	dependsOn test
}



bootJar {
	dependsOn asciidoctor
	delete file('src/main/resources/static/docs/*')
	copy {
		from asciidoctor.outputDir
		into "src/main/resources/static/docs"
	}
}



configurations {
	compileOnly {
		extendsFrom annotationProcessor
	}
	asciidoctorExtensions
}

📌 회원가입 API

@RestController
@RequestMapping("/api/member")
public class SignupAPI {

    private final SignupCommand signupCommand;

    public SignupAPI(SignupCommand signupCommand) {
        this.signupCommand = signupCommand;
    }

    @PostMapping(value = "/signup", consumes = {"multipart/form-data"})
    public ResponseEntity<ApiResponse> signup(
            @RequestPart @Valid SignupRequest request,
            @RequestPart("file")MultipartFile file

            ) {
        Member signup = signupCommand.signup(request, file);
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(ApiResponse.of(signup.getId(), HttpStatus.CREATED));
    }
}

회원가입API의 경우 mult-part 방식으로 받습니다.

📌 로그인 API

@RestController
@RequestMapping("/api/member")
public class LoginAPI {

    private final LoginService loginService;

    public LoginAPI(LoginService loginService) {
        this.loginService = loginService;
    }

    @PostMapping("/login")
    public ResponseEntity login(@RequestBody @Valid LoginRequest loginRequest) {
        Token token = loginService.login(loginRequest);
        return ResponseEntity
                .status(HttpStatus.OK)
                .header(SecurityFilter.AUTHORIZATION_HEADER, token.getAccessToken())
                .header(SecurityFilter.SESSION_ID, token.getRefreshToken())
                .header(SecurityFilter.AUTHORITY, token.getRole().toString())
                .build();
    }
}

로그인 API는 json 바디로 받습니다.
자 이제 위 두 API를 인수테스트 및 문서화를 진행해 보겠습니다.

인수테스트 및 문서화 코드

📌 회원가입 테스트

@DisplayName("회원가입 기능 인수 테스트")
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
@Import(S3Configuration.class)
public class SignupAcceptanceTest extends DatabaseTestBase {

    public static final String BASE_URL = "http://localhost";
    @LocalServerPort
    private int port = 8080;


    private RequestSpecification documentationSpec = new RequestSpecBuilder()
            .setPort(port)
            .setBaseUri(BASE_URL)
            .build();

    @BeforeAll
    public void configureRestAssured() {
        RestAssured.port = port;
        baseURI = BASE_URL;
    }


    @BeforeEach
    public void setUpRestDocs(RestDocumentationContextProvider restDocumentation) {
        this.documentationSpec = new RequestSpecBuilder()
                .addFilter(RestAssuredRestDocumentation.documentationConfiguration(restDocumentation))
                .build();
    }

    @Test
    @DisplayName("회원가입 API 테스트")
    public void given_valid_signup_info_when_signup_then_id() {
        // given - loginId, password, studentNumber
        JsonObject jsonObject = getSignupMember();
        byte[] fileByte = "Hello, World".getBytes();

        RequestSpecification signup = RestAssured.given(documentationSpec)
                .multiPart("request", jsonObject.toString(), APPLICATION_JSON_VALUE)
                .contentType(APPLICATION_JSON_VALUE)
                .multiPart("file", "file.png", fileByte, MULTIPART_FORM_DATA_VALUE)
                .contentType(MULTIPART_FORM_DATA_VALUE)
                .filter(document(
                        "users-post",
                        getRequestPartsSnippet(),
                        getRequestPartFieldsSnippet(),
                        getResponseFieldsSnippet()
                ));

        // then - signup
        signup.when()
                .post("/api/member/signup")
                .then()
                .statusCode(HttpStatus.CREATED.value());
    }

    private RequestPartsSnippet getRequestPartsSnippet() {
        return requestParts(
                partWithName("file").description("학생증 사진"),
                partWithName("request").description("유저 정보")
        );
    }

    private RequestPartFieldsSnippet getRequestPartFieldsSnippet() {
        return requestPartFields(
                "request",
                fieldWithPath("loginId").description("로그인 아이디"),
                fieldWithPath("password").description("패스워드"),
                fieldWithPath("studentNumber").description("학번")
        );
    }

    private ResponseFieldsSnippet getResponseFieldsSnippet() {
        return responseFields(
                fieldWithPath("eventTime").type(JsonFieldType.STRING).description("이벤트 시간"),
                fieldWithPath("status").type(JsonFieldType.STRING).description("HTTP 상태값"),
                fieldWithPath("code").type(JsonFieldType.NUMBER).description("HTTP 상태 코드"),
                fieldWithPath("data").type(JsonFieldType.NUMBER).description("유저 id값")
        );
    }

    private static JsonObject getSignupMember() {
        JsonObject jsonObject = new JsonObject();
        jsonObject.addProperty("loginId", "abcd1234");
        jsonObject.addProperty("password", "Abcd1234@!");
        jsonObject.addProperty("studentNumber", 2020110110);
        return jsonObject;
    }
}

• requestParts - multi-part로 어떤 데이터가 들어오는지 검증합니다.
• requestPartFields - 각 part에 데이터의 필드에 대해 검증합니다.
• fieldWithPath - 응답 데이터에 대해 검증합니다.

📌 로그인 테스트

	...
        @DisplayName("로그인 API 테스트")
    @Test
    public void given_when_then() {
        // given - loginId, password
        String loginId = "abcd1234";
        String password = "Abcd1234@!";
        JsonObject jsonObject = getLoginMember(loginId, password);

        // 회원가입
        Member member = signupFixture.signupMember(loginId, password);

        // 승인된 멤버로 전환
        approvalChangeCommand.changeApproval(member.getId());

        // when - login
        given(documentationSpec)
                .contentType(ContentType.JSON)
                .body(jsonObject.toString())
                .filter(document(
                        "login",
                        getRequestFieldsSnippet(),
                        getResponseHeadersSnippet()
                ))
                .when().post("/api/member/login").then().statusCode(HttpStatus.OK.value());
    }

    private static JsonObject getLoginMember(String loginId, String password) {
        JsonObject jsonObject = new JsonObject();
        jsonObject.addProperty("loginId", loginId);
        jsonObject.addProperty("password", password);
        return jsonObject;
    }

    private ResponseHeadersSnippet getResponseHeadersSnippet() {
        return responseHeaders(
                headerWithName(SecurityFilter.AUTHORIZATION_HEADER).description("Access token"),
                headerWithName(SecurityFilter.SESSION_ID).description("Refresh token"),
                headerWithName(SecurityFilter.AUTHORITY).description("멤버 권한")
        );
    }

    private RequestFieldsSnippet getRequestFieldsSnippet() {
        return requestFields(
                fieldWithPath("loginId").type(JsonFieldType.STRING).description("로그인 아이디"),
                fieldWithPath("password").type(JsonFieldType.STRING).description("패스워드")
        );
    }
}

    

• requestFields - @requestBody로 요청을 할 경우 사용하는 검증입니다.
• fieldWithPath - json각 필드에 대해 검증합니다.
• responseHeaders - 응답하는 헤더값에 대해 검증합니다.
• headerWithName - 각 헤더값에 대해 검증합니다.

테스트를 진행합니다.

./gradlew test

문서화에 필요한 파일들이 생깁니다.
이 파일들을 가지고 문서화 파일을 작성합니다.

[[resources-member-post]]
== 회원가입
=== POST
==== HTTP request
file은 multipart/form-data로 주세요.

png, jpeg 등
include::{snippets}/users-post/curl-request.adoc[]
include::{snippets}/users-post/request-parts.adoc[]

request에 넣을 json 유저 정보

include::{snippets}/users-post/request-part-request-fields.adoc[]


==== HTTP response
include::{snippets}/users-post/http-response.adoc[]
include::{snippets}/users-post/response-fields.adoc[]

[[resources-login]]
== 로그인
=== POST
==== http request
include::{snippets}/login/http-request.adoc[]
include::{snippets}/login/request-fields.adoc[]

==== http response
http 헤더에 담아서 드립니다.
include::{snippets}/login/http-response.adoc[]
include::{snippets}/login/response-headers.adoc[]

그럼 접속 가능한 html파일을 만들어 봅시다.

./gradlew bootJar

그러면 이런식으로 문서화가 진행됩니다.

사용 후기

• Swagger에 비해 공수가 많이들긴 하지만 Swagger의 기존 비즈니스 로직에 문서화 코드가 침범하는게 불만족 스럽던 저는 만족스럽습니다.
• 빠르게 개발해야 하는 프로젝트에는 어울리진 않을거 같습니다.

---

참고

https://rest-assured.io/
https://docs.spring.io/spring-restdocs/docs/2.0.7.RELEASE/reference/html5/
http://wiki.hash.kr/index.php/%ED%85%8C%EC%8A%A4%ED%8A%B8
https://scshim.tistory.com/321