Spring Boot: автоматически настроенные Spring REST Docs тесты

апреля 16, 2020

Вы можете использовать аннотацию @AutoConfigureRestDocs, чтобы использовать Spring REST Docs в своих тестах с Mock MVC, REST Assured или WebTestClient. Это устраняет необходимость расширения JUnit в Spring REST Docs.

@AutoConfigureRestDocs можно использовать для переопределения выходного каталога по умолчанию (target/generated-snippets, если вы используете Maven, или build/generated-snippets, если вы используете Gradle). Его также можно использовать для настройки хоста, схемы и порта, которые появляются в любых задокументированных URI.

Автоматически настроенные Spring REST Docs тесты с Mock MVC

@AutoConfigureRestDocs настраивает bean-компонент MockMvc для использования Spring REST Docs. Вы можете внедрить его с помощью @Autowired и использовать его в своих тестах, как обычно, когда используете Mock MVC и Spring REST Docs, как показано в следующем примере:

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(UserController.class)
@AutoConfigureRestDocs
class UserDocumentationTests {

    @Autowired
    private MockMvc mvc;

    @Test
    void listUsers() throws Exception {
        this.mvc.perform(get("/users").accept(MediaType.TEXT_PLAIN))
                .andExpect(status().isOk())
                .andDo(document("list-users"));
    }

}

Если вам требуется больший контроль над конфигурацией Spring REST Docs, чем это предусмотрено атрибутами @AutoConfigureRestDocs, вы можете использовать bean-компонент RestDocsMockMvcConfigurationCustomizer, как показано в следующем примере:

@TestConfiguration
static class CustomizationConfiguration
        implements RestDocsMockMvcConfigurationCustomizer {

    @Override
    public void customize(MockMvcRestDocumentationConfigurer configurer) {
        configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
    }

}

Если вы хотите использовать поддержку Spring REST Docs для параметризованного выходного каталога, вы можете создать bean-компонент RestDocumentationResultHandler. Автоматическая конфигурация вызывает alwaysDo с этим обработчиком результатов, в результате чего каждый вызов MockMvc автоматически генерирует фрагменты по умолчанию. В следующем примере показано определение RestDocumentationResultHandler:

@TestConfiguration(proxyBeanMethods = false)
static class ResultHandlerConfiguration {

    @Bean
    public RestDocumentationResultHandler restDocumentation() {
        return MockMvcRestDocumentation.document("{method-name}");
    }

}

Автоматически настроенные Spring REST Docs тесты с WebTestClient

@AutoConfigureRestDocs также можно использовать с WebTestClient. Вы можете добавить его, используя @Autowired, и использовать его в своих тестах, как обычно, когда используете документы @WebFluxTest и Spring REST, как показано в следующем примере:

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.test.web.reactive.server.WebTestClient;

import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

@WebFluxTest
@AutoConfigureRestDocs
class UsersDocumentationTests {

    @Autowired
    private WebTestClient webTestClient;

    @Test
    void listUsers() {
        this.webTestClient.get().uri("/").exchange().expectStatus().isOk().expectBody()
                .consumeWith(document("list-users"));
    }

}

Если вам требуется больший контроль над конфигурацией Spring REST Docs, чем это предусмотрено атрибутами @AutoConfigureRestDocs, вы можете использовать bean-компонент RestDocsWebTestClientConfigurationCustomizer, как показано в следующем примере:

@TestConfiguration(proxyBeanMethods = false)
public static class CustomizationConfiguration implements RestDocsWebTestClientConfigurationCustomizer {

    @Override
    public void customize(WebTestClientRestDocumentationConfigurer configurer) {
        configurer.snippets().withEncoding("UTF-8");
    }

}

Автоматически настроенные Spring REST Docs тесты с REST Assured

@AutoConfigureRestDocs делает компонент RequestSpecification, предварительно настроенный для использования Spring REST Docs, доступным для ваших тестов. Вы можете добавить его, используя @Autowired, и использовать его в своих тестах, как обычно, когда используете документы REST Assured и Spring REST, как показано в следующем примере:

import io.restassured.specification.RequestSpecification;
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.web.server.LocalServerPort;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.is;
import static org.springframework.restdocs.restassured3.RestAssuredRestDocumentation.document;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureRestDocs
class UserDocumentationTests {

    @Test
    void listUsers(@Autowired RequestSpecification documentationSpec, @LocalServerPort int port) {
        given(documentationSpec).filter(document("list-users")).when().port(port).get("/").then().assertThat()
                .statusCode(is(200));
    }

}

Если вам требуется больший контроль над конфигурацией Spring REST Docs, чем это предусмотрено атрибутами @AutoConfigureRestDocs, можно использовать bean-компонент RestDocsRestAssuredConfigurationCustomizer, как показано в следующем примере:

@TestConfiguration(proxyBeanMethods = false)
public static class CustomizationConfiguration implements RestDocsRestAssuredConfigurationCustomizer {

    @Override
    public void customize(RestAssuredRestDocumentationConfigurer configurer) {
        configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
    }

}

Поиск по этому блогу

Java Blog