Практический кейс: как быстро развернуть Testcontainer PostgreSQL для Spring Boot API

Приветствую тебя, уважаемый читатель Хабра! Меня зовут Артур Вартанян и я работаю в компании “Рексофт” Java-разработчиком.

Тема с testcontainer-ами относительно не новая, первые статьи на англоязычных ресурсах встречаются с 2016 года, но не смотря на это, до сих пор на просторах веба крайне мало гайдов для их развертывания из коробки. В большинстве своем это туториалы, где собрана солянка из зависимостей и аннотаций, которые мало того, что не нужны, но еще и могут запутать разработчика, решившего  с ними познакомиться. В этой статье я опишу свой практический кейс по развертыванию тестовых контейнеров для базы данных PostgreSQL. Основная задача их использования — быстрый deploy нужного сервиса в контейнере за небольшое время. В дополнении для наглядности запустим туда FlyWay миграции.

Мы не будем говорить о плюсах и минусах контейнеризации и интеграционных тестов, а сразу приступим к делу.

Нам потребуется:

• Docker. Он нужен для того, чтобы запускать контейнер и управлять им.

• Spring MVC API (REST) с некоторым количеством тестов. Приложение, которое будет запускать тесты в контейнере, должно иметь хотя бы один интеграционный тест, иначе смысла в использовании контейнера нет.

Класс контроллера:

@RestController @RequiredArgsConstructor @RequestMapping("/api/authentication") public class AuthenticationController {      private final AuthenticationService authenticationService;      @PostMapping(value = "/login")     public ResponseEntity<LoginResponseDTO> login(@RequestBody @Validated LoginCredentialDTO loginCredentialDTO)             throws NamingException {         return new ResponseEntity<>(authenticationService.login(loginCredentialDTO), HttpStatus.OK);     } }

Класс тестов:

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;  import com.fasterxml.jackson.databind.ObjectMapper; import org.junit.Assertions; import org.junit.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.mock.mockito.MockBean; import org.springframework.http.MediaType; import org.springframework.test.web.servlet.MockMvc; import ru.project.path.dto.LoginCredentialDTO;  import java.time.LocalDateTime; import java.util.List;   class AuthenticationControllerTest {      @Autowired     MockMvc mockMvc;      @Autowired     ObjectMapper objectMapper;       @Test     void loginOkWithLogging() throws Exception {         LoginCredentialDTO loginCredentialDTO = generateDTOWithCorrectCredentials();         mockMvc.perform(post("/api/authentication/login")                         .content(objectMapper.writeValueAsString(loginCredentialDTO))                         .contentType(MediaType.APPLICATION_JSON))                 .andExpect(status().isOk());     }      @Test     void loginWithBadCredentials() throws Exception {         mockMvc.perform(post("/api/authentication/login")                 .content(objectMapper.writeValueAsString(generateDTOWithIncorrectCredentials()))                 .contentType(MediaType.APPLICATION_JSON)         ).andExpect(status().isBadRequest());     }      @Test     void loginWithBadValidation() throws Exception {         mockMvc.perform(post("/api/authentication/login")                 .content(objectMapper.writeValueAsString(generateDTOWithBadValidationCredentials()))                 .contentType(MediaType.APPLICATION_JSON)         ).andExpect(status().isBadRequest());     } }

Для того, чтобы переписать код под использование testcontainers, необходимо добавить всего лишь 3 зависимости (для примера используется Gradle / версии актуальны на момент написания статьи):

   testImplementation 'org.springframework.boot:spring-boot-starter-test:2.7.2'     testImplementation "org.testcontainers:postgresql:1.17.6"     testImplementation "org.testcontainers:junit-jupiter:1.17.6"

• spring-boot-starter-test — для поднятия контекста тестов

• testcontainers:postgresql — PostgreSQL для контейнера

• testcontainers:junit-jupiter — JUnit Jupiter для контейнера

Если проект не специфичный и не должен поддерживать связку legacy тестов вперемешку с новыми, то других зависимостей не требуется! Иначе из-за одной неверно подтянутой аннотации testcontainer-ы могут просто не подняться, и понять в чем дело будет тяжело, так как логи об ошибке не будут явно указывать на проблему зависимостей. Все свои другие библиотеки от JUnit, которые вы использовали до добавления testcontainer-ов нужно удалить — они ни к чему.

Теперь, после добавления нужных библиотек, необходимо создать класс, который будет отвечать за конфигурирование и настройку контейнера:

import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.test.util.TestPropertyValues; import org.springframework.context.ApplicationContextInitializer; import org.springframework.context.ConfigurableApplicationContext; import org.springframework.test.context.ContextConfiguration; import org.springframework.test.context.TestPropertySource; import org.testcontainers.containers.PostgreSQLContainer; import org.testcontainers.junit.jupiter.Container; import org.testcontainers.junit.jupiter.Testcontainers;  /**  * General class for test containers.  */ @SpringBootTest @Testcontainers @AutoConfigureMockMvc(addFilters = false) @ContextConfiguration(initializers = {SpringBootApplicationTest.Initializer.class}) @TestPropertySource(properties = {"spring.config.location=classpath:application-properties.yml"}) public class SpringBootApplicationTest {      private static final String DATABASE_NAME = "spring-app";      @Container     public static PostgreSQLContainer<?> postgreSQLContainer = new PostgreSQLContainer<>("postgres:11.1")             .withReuse(true)             .withDatabaseName(DATABASE_NAME);      static class Initializer implements ApplicationContextInitializer<ConfigurableApplicationContext> {         public void initialize(ConfigurableApplicationContext configurableApplicationContext) {             TestPropertyValues.of(                     "CONTAINER.USERNAME=" + postgreSQLContainer.getUsername(),                     "CONTAINER.PASSWORD=" + postgreSQLContainer.getPassword(),                     "CONTAINER.URL=" + postgreSQLContainer.getJdbcUrl()             ).applyTo(configurableApplicationContext.getEnvironment());         }     } }

@SpringBootTest — поднимает ApplicationContext для запуска тестов и имитирует среду для тестирования близкую к полноценному запуску приложения.

@Testcontainers — аннотация для JUpiter интеграционных тестов. Находит все поля, помеченные аннотацией @Container, и вызывает их методы контроля за жизненным циклом для контейнера.

@AutoConfigureMockMvc — в тестах я часто использую MockMVC класс, поэтому для его настройки из  коробки я использую данную аннотацию.

@ContextConfiguration — аннотация определяет метаданные уровня класса, которые используются для определения того, как загружать и настраивать ApplicationContext для интеграционных тестов. На самом деле, тут можно обойтись и без данной аннотации, так как мы уже используем @SpringBootTest, но с ним код будет чище и появится возможность сразу создавать переменные окружения для конфигураций ApplicationContext-а. 

@TestPropertySource — указываем путь нахождения файла application.properties для тестов.

Статичное поле postgreSQLContainer, помеченное аннотацией @Container, по сути является флажком для аннотации @TestContainer, который понимает, что необходимо запустить тестовый контейнер PostgreSQL и управлять его жизненным циклом.

Тут же вызываются методы withReuse() и withDatabaseName().

withResure() с флажком true — держит контейнер в активном состоянии до тех пор, пока не исполнятся все тестовые методы, а также дает возможность переиспользовать контейнер для каждого теста без его затухания и поднятия нового экземпляра.

withDatabaseName() — получает на вход название базы данных (можно указать рандомный и также вынести в переменную окружения — см.ниже).

Вложенный статичный класс Initializer реализует ApplicationContextInitializer и при инициализации создает переменные окружения. В TestPropertyValues  мы их и создаем по принципу ключ-значение.

По сути после поднятия контекста у нас будут доступны три переменные, которые мы можем использовать там, где это необходимо, например, при накатке FlyWay миграций.

Класс самих тестов также немного преобразуется и станет наследником SpringBootApplicationTest, одновременно меняя свои аннотации на JUnit Jupiter:

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;  import com.fasterxml.jackson.databind.ObjectMapper; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.mock.mockito.MockBean; import org.springframework.http.MediaType; import org.springframework.test.web.servlet.MockMvc; import ru.project.path.SpringBootApplicationTest;  import java.time.LocalDateTime; import java.util.List;  /**  * Test class for AuthenticationController  */ class AuthenticationControllerTest extends SpringBootApplicationTest {      @Autowired     MockMvc mockMvc;      @Autowired     ObjectMapper objectMapper;         @Test     void loginOkWithLogging() throws Exception {         LoginCredentialDTO loginCredentialDTO = generateDTOWithCorrectCredentials();         mockMvc.perform(post("/api/authentication/login")                         .content(objectMapper.writeValueAsString(loginCredentialDTO))                         .contentType(MediaType.APPLICATION_JSON))                 .andExpect(status().isOk());     }      @Test     void loginWithBadCredentials() throws Exception {         mockMvc.perform(post("/api/authentication/login")                 .content(objectMapper.writeValueAsString(generateDTOWithIncorrectCredentials()))                 .contentType(MediaType.APPLICATION_JSON)         ).andExpect(status().isBadRequest());     }      @Test     void loginWithBadValidation() throws Exception {         mockMvc.perform(post("/api/authentication/login")                 .content(objectMapper.writeValueAsString(generateDTOWithBadValidationCredentials()))                 .contentType(MediaType.APPLICATION_JSON)         ).andExpect(status().isBadRequest());     } }

Напоследок application-properties.yml файл (создаем в тестах новый файл в папке ресурсов):

#Spring Boot spring:  datasource:     own:      username: ${CONTAINER.USERNAME}      password: ${CONTAINER.PASSWORD}      url: ${CONTAINER.URL}

Так как приложение во время работы должно использовать базы данных от тестконтейнера, необходимо прописать для него строку подключения. Как уже отмечалось выше, в переменные окружения при поднятии тестового контекста уже все было вынесено, а именно:

CONTAINER.URL — строка подключения к БД

CONTAINER.USERNAME — имя пользователя

CONTAINER.PASSWORD — пароль пользователя

Подставив их в application-properties.yml файл, можно получить полностью настроенный контекст приложения.

P.S. При указании в application-properties значений с окружения, используется запись вида: ${НАЗВАНИЕ_ПЕРЕМЕННОЙ}.

Дополнение:

Для большей наглядности на базу PostgreSQL от тестконтейнера накатим FlyWay миграции, чтобы получить базу идентичную с приложением.

Для этого в тестовый application-properties.yml файл нужно добавить всего лишь пару строк кода, где также будут указаны данные для подключения и запуска миграций:

flyway:    user: ${CONTAINER.USERNAME}    password: ${CONTAINER.PASSWORD}    url: ${CONTAINER.URL}

При запуске тестовых классов или методов, в Docker (Docker Desktop в моем случае) можно будет увидеть поднятый контейнер, который сразу же после завершения тестов потухнет.

Надеюсь данная статья была для Вас полезна и в дальнейшем будет помогать тратить меньше времени на запуск и настройку тестовых контейнеров, ведь один из главных смыслов их использования — это быстрый deploy нужного сервиса в контейнере за небольшое время.