Основные возможности

По умолчанию, если указанное расположение данных конфигурации не существует, Spring Boot выбросит исключение ConfigDataLocationNotFoundException, и ваше приложение не запустится.

Если вы хотите указать расположение, но не возражаете, если оно не всегда существует, вы можете использовать префикс optional:. Вы можете использовать этот префикс со свойствами spring.config.location и spring.config.additional-location, а также с объявлениями spring.config.import.

Например, значение spring.config.import optional:file:./myconfig.properties позволяет вашему приложению запускаться, даже если файл myconfig.properties отсутствует.

Если вы хотите игнорировать все ConfigDataLocationNotFoundExceptions и всегда продолжать запуск приложения, вы можете использовать свойство spring.config.on-not-found. Установите значение на ignore с помощью SpringApplication.setDefaultProperties(…​) или системной/средовой переменной.

Если расположение файла конфигурации включает символ * для последнего сегмента пути, оно считается расположением с подстановочными знаками. Подстановочные знаки расширяются при загрузке конфигурации, поэтому проверяются также непосредственные подкаталоги. Расположения с подстановочными знаками особенно полезны в среде, например, Kubernetes, когда есть несколько источников свойств конфигурации.

Например, если у вас есть конфигурация Redis и конфигурация MySQL, вы можете захотеть сохранить эти две части конфигурации раздельно, при этом потребовав, чтобы обе были присутствовать в файле application.properties. Это может привести к двум отдельным файлам application.properties, размещенным в разных расположениях, таких как /config/redis/application.properties и /config/mysql/application.properties. В таком случае, наличие расположения с подстановочным знаком config/*/ приведет к обработке обоих файлов.

По умолчанию Spring Boot включает config/*/ в стандартные расположения поиска. Это означает, что будут проверяться все подкаталоги каталога /config вне вашего JAR-файла.

Вы можете использовать расположения с подстановочными знаками самостоятельно с помощью свойств spring.config.location и spring.config.additional-location.

Помимо файлов свойств application, Spring Boot также попытается загрузить файлы, специфичные для профиля, используя соглашение об именовании application-{profile}. Например, если ваше приложение активирует профиль с именем prod и использует файлы YAML, то будут рассмотрены как application.yaml, так и application-prod.yaml.

Свойства, специфичные для профиля, загружаются из тех же мест, что и стандартные файлы application.properties, при этом файлы, специфичные для профиля, всегда переопределяют неспецифичные. Если указано несколько профилей, применяется стратегия «последнее значение выигрывает». Например, если профили prod,live указаны свойством spring.profiles.active, значения в application-prod.properties могут быть переопределены значениями из application-live.properties.

У Environment есть набор профилей по умолчанию (по умолчанию, [default]), которые используются, если активные профили не заданы. Другими словами, если профили не активированы явно, то учитываются свойства из application-default.

Свойства приложения могут импортировать дополнительные данные конфигурации из других мест, используя свойство spring.config.import. Импорты обрабатываются по мере обнаружения и рассматриваются как дополнительные документы, вставленные сразу под документом, который объявляет импорт.

Например, в вашем классе application.properties может быть следующий файл:

Это вызовет импорт файла dev.properties в текущей директории (если такой файл существует). Значения из импортированного dev.properties будут иметь приоритет над файлом, который инициировал импорт. В приведённом примере dev.properties может переопределить значение spring.application.name.

Импорт будет осуществлен только один раз, независимо от того, сколько раз он объявлен. Порядок объявления импорта внутри одного документа в файлах свойств/YAML не имеет значения. Например, два примера ниже дают один и тот же результат:

В обоих примерах значения из файла my.properties будут иметь приоритет над файлом, который инициировал импорт.

Несколько расположений могут быть указаны под одним ключом spring.config.import. Расположения будут обрабатываться в порядке их определения, а более поздние импорты будут иметь приоритет.

Некоторые облачные платформы не могут добавить расширение файла к объёмно смонтированным файлам. Чтобы импортировать эти файлы без расширения, необходимо дать Spring Boot подсказку о том, как их загружать. Это можно сделать, поместив подсказку расширения в квадратные скобки.

Например, предположим, что у вас есть файл /etc/config/myconfig, который вы хотите импортировать как YAML. Вы можете импортировать его из вашего application.properties, используя следующее:

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

В качестве альтернативы переменным окружения многие облачные платформы теперь позволяют отображать конфигурацию в смонтированных томах данных. Например, Kubernetes может монтировать тома как ConfigMaps, так и Secrets.

Существует два распространённых шаблона монтирования томов:

В первом случае вы можете импортировать YAML- или Properties-файл напрямую, используя spring.config.import, как описано выше. Во втором случае необходимо использовать префикс configtree:, чтобы Spring Boot знал, что ему нужно экспонировать все файлы как свойства.

В качестве примера, предположим, что Kubernetes смонтировал следующий том:

Содержимое файла username будет значением конфигурации, а содержимое файла password — секретом.

Для импорта этих свойств вы можете добавить следующее в свой файл application.properties или application.yaml:

Затем вы можете получить доступ к или внедрить свойства myapp.username и myapp.password из Environment обычным способом.

Если у вас несколько деревьев конфигурации для импорта из одной родительской папки, вы можете использовать сокращение с подстановочным знаком. Любое расположение configtree:, которое заканчивается на /*/, импортирует всех непосредственных потомков как деревья конфигурации. Как и при импорте без подстановочного знака, имена папок и файлов в каждом дереве конфигурации образуют имя свойства.

Например, если данный том:

Вы можете использовать configtree:/etc/config/*/ в качестве расположения импорта:

Это добавит свойства db.username, db.password, mq.username и mq.password.

Деревья конфигурации также могут использоваться для Docker-секретов. Когда служба Docker swarm получает доступ к секрету, секрет монтируется в контейнер. Например, если секрет с именем db.password смонтирован по пути /run/secrets/, вы можете сделать db.password доступным для среды Spring следующим образом:

Значения в файлах application.properties и application.yaml фильтруются через существующие Environment при использовании, поэтому вы можете ссылаться на ранее определенные значения (например, из системных свойств или переменных окружения). Стандартный синтаксис подстановки свойств ${name} можно использовать где угодно в значении. Подстановки свойств также могут указывать значение по умолчанию, используя : для разделения значения по умолчанию и имени свойства, например ${name:default}.

Использование подстановок с и без значений по умолчанию показано в следующем примере:

Предполагая, что свойство username не было установлено в другом месте, app.description будет иметь значение MyApp is a Spring Boot application written by Unknown.

Spring Boot позволяет разделять один физический файл на несколько логических документов, каждый из которых добавляется независимо. Документы обрабатываются в порядке следования сверху вниз. Более поздние документы могут перезаписывать свойства, определённые в предыдущих.

Для файлов application.yaml используется стандартный синтаксис YAML для нескольких документов. Три последовательных дефиса обозначают конец одного документа и начало следующего.

Например, в следующем файле два логических документа:

Для файлов application.properties используется специальный комментарий #--- или !--- для обозначения разбиения документов:

Иногда бывает полезно активировать заданный набор свойств только при выполнении определенных условий. Например, у вас могут быть свойства, относящиеся только к активному профилю.

Вы можете условно активировать документ свойств, используя spring.config.activate.*.

Доступны следующие свойства активации:

Например, следующее указывает, что второй документ активен только при работе в Kubernetes и только тогда, когда активны профили «prod» или «staging»:

Можно связать объект, объявляющий стандартные свойства JavaBean, как показано в следующем примере:

Предыдущий POJO определяет следующие свойства:

Пример в предыдущем разделе можно переписать в неизменяемом виде, как показано в следующем примере:

В этой настройке наличие единственного параметризованного конструктора подразумевает использование связывания по конструктору. Это означает, что связующий элемент найдет конструктор с параметрами, которые вы хотите связать. Если у вашего класса несколько конструкторов, аннотация @ConstructorBinding может использоваться для указания конструктора, который нужно использовать для связывания по конструктору. Чтобы отключить связывание по конструктору для класса с единственным параметризованным конструктором, конструктор должен быть аннотирован с помощью @Autowired. Связывание по конструктору можно использовать с записями. Если ваша запись не имеет нескольких конструкторов, нет необходимости использовать @ConstructorBinding.

Вложенные члены класса, связанного по конструктору (например, Security в приведенном выше примере), также будут связаны через свой конструктор.

Значения по умолчанию можно задать с помощью @DefaultValue для параметров конструктора и компонентов записей. Сервис преобразования будет применен для преобразования аннотированного String значения в целевой тип отсутствующего свойства.

Если обратиться к предыдущему примеру, если ни одно свойство не привязано к Security, экземпляр MyProperties будет содержать значение null для security. Чтобы он содержал непустой экземпляр Security даже когда ни одно свойство не привязано к нему (при использовании Kotlin, это потребует параметров username и password Security быть объявлены как необязательные, поскольку у них нет значений по умолчанию), используйте пустую аннотацию @DefaultValue:

Spring Boot предоставляет инфраструктуру для привязки типов @ConfigurationProperties и регистрации их как компонентов. Вы можете либо включить свойства конфигурации для каждого класса по отдельности, либо включить сканирование свойств конфигурации, которое работает аналогично сканированию компонентов.

Иногда классы, аннотированные с помощью @ConfigurationProperties, могут не подходить для сканирования, например, если вы разрабатываете собственные автоконфигурации или хотите включить их условно. В таких случаях укажите список типов для обработки с помощью аннотации @EnableConfigurationProperties. Это можно сделать в любом классе @Configuration, как показано в следующем примере:

Чтобы использовать сканирование свойств конфигурации, добавьте аннотацию @ConfigurationPropertiesScan к своему приложению. Обычно она добавляется к главному классу приложения, аннотированному с помощью @SpringBootApplication, но ее можно добавить к любому классу @Configuration. По умолчанию сканирование будет выполняться из пакета класса, который объявляет аннотацию. Если вы хотите определить конкретные пакеты для сканирования, вы можете сделать это, как показано в следующем примере:

Рекомендуется, чтобы @ConfigurationProperties работал только со средой и, в частности, не инжектировал другие компоненты из контекста. Для особых случаев можно использовать инъекцию через сеттер или любой из интерфейсов *Aware, предоставляемых фреймворком (например, EnvironmentAware, если вам нужен доступ к Environment). Если вы все же хотите инжектировать другие компоненты с помощью конструктора, компонент конфигурации свойств должен быть аннотирован с помощью @Component и использовать привязку свойств на основе JavaBean.

Этот стиль конфигурации особенно хорошо работает с внешней YAML-конфигурацией, как показано в следующем примере:

Чтобы работать с @ConfigurationProperties бинсами, вы можете вводить их так же, как и любые другие бинсы, как показано в следующем примере:

Помимо использования @ConfigurationProperties для аннотирования класса, вы также можете использовать его для общедоступных @Bean методов. Это может быть особенно полезно, когда вы хотите привязать свойства к компонентам сторонних библиотек, которые находятся вне вашего контроля.

Для настройки бинса из Environment свойств добавьте @ConfigurationProperties к его регистрации бинсов, как показано в следующем примере:

Любое свойство JavaBean, определённое с префиксом another, сопоставляется с этим AnotherComponent бинсом аналогично предыдущему примеру SomeProperties.

Spring Boot использует некоторые правила гибкой привязки свойств Environment к объектам @ConfigurationProperties, поэтому точное совпадение имени свойства Environment и имени свойства объекта не требуется. Типичные примеры, где это полезно, включают свойства среды, разделенные дефисом (например, context-path привязывается к contextPath) и свойства среды с заглавными буквами (например, PORT привязывается к port).

В качестве примера рассмотрим следующий класс @ConfigurationProperties:

С указанным кодом могут использоваться следующие имена свойств:

При конфигурировании списков в нескольких местах перезапись происходит заменой всего списка.

Например, предположим объект MyPojo с атрибутами name и description, которые по умолчанию являются null. Следующий пример демонстрирует список объектов MyPojo из MyProperties:

Рассмотрим следующую конфигурацию:

Если профиль dev не активен, MyProperties.list содержит одну запись MyPojo, как определено ранее. Однако, если профиль dev активирован, list по-прежнему содержит только одну запись (с именем my another name и описанием null). Эта конфигурация не добавляет второй экземпляр MyPojo в список и не объединяет элементы.

Когда List указан в нескольких профилях, используется только тот, у которого приоритет выше. Рассмотрим следующий пример:

В предыдущем примере, если профиль dev активен, MyProperties.list содержит одну запись MyPojo (с именем my another name и описанием null). Для YAML можно использовать как списки, разделенные запятыми, так и списки YAML для полной перезаписи содержимого списка.

Для свойств Map можно привязываться к значениям свойств из нескольких источников. Однако для одного и того же свойства в нескольких источниках используется тот, у которого приоритет выше. Следующий пример демонстрирует Map<String, MyPojo> из MyProperties:

Рассмотрим следующую конфигурацию:

Если профиль dev не активен, MyProperties.map содержит одну запись с ключом key1 (с именем my name 1 и описанием my description 1). Однако, если профиль dev включен, map содержит две записи с ключами key1 (с именем dev name 1 и описанием my description 1) и key2 (с именем dev name 2 и описанием dev description 2).

Spring Boot пытается привести внешние свойства приложения к нужному типу при привязке к @ConfigurationProperties биндам. Если вам нужна настройка преобразования типов, вы можете предоставить ConversionService бин (с именем бина conversionService) или пользовательские редакторы свойств (через CustomEditorConfigurer бин) или пользовательские Converters (с определениями бинов, помеченных как @ConfigurationPropertiesBinding).

Аннотация @Value — это основная функция контейнера, и она не предоставляет те же возможности, что и типизированные свойства конфигурации. В следующей таблице обобщены возможности, поддерживаемые @ConfigurationProperties и @Value:

Если вы определяете набор ключей конфигурации для собственных компонентов, рекомендуется сгруппировать их в POJO, аннотированном с помощью @ConfigurationProperties. Это обеспечит вам структурированный, типизированный объект, который можно ввести в свои собственные бины.

SpEL выражения из файлов свойств приложения не обрабатываются во время разбора этих файлов и заполнения среды. Однако можно записать выражение SpEL в @Value. Если значение свойства из файла свойств приложения является выражением SpEL, оно будет вычислено при использовании через @Value.

Если Spring MVC доступен, настраивается обычный контекст приложения на основе MVC. Если у вас только Spring WebFlux, мы определим это и настроим контекст приложения на основе WebFlux вместо этого.

Если оба присутствуют, Spring MVC имеет приоритет. Если вы хотите протестировать реактивное веб-приложение в этом сценарии, необходимо установить свойство spring.main.web-application-type:

Если вы знакомы с Spring Test Framework, вы, возможно, привыкли использовать @ContextConfiguration(classes=…​) для указания, какой Spring @Configuration загружать. Или, возможно, вы часто использовали вложенные @Configuration классы в своих тестах.

При тестировании приложений Spring Boot это часто не требуется. Аннотации @*Test Spring Boot автоматически ищут основную конфигурацию, когда вы не определяете её явно.

Алгоритм поиска работает вверх с пакета, содержащего тест, до тех пор, пока не найдет класс, помеченный аннотациями @SpringBootApplication или @SpringBootConfiguration. При условии разумной структуры вашего кода, ваша основная конфигурация обычно находится.

Если вы хотите настроить основную конфигурацию, вы можете использовать вложенный класс @TestConfiguration. В отличие от вложенного класса @Configuration, который бы использовался вместо основной конфигурации вашего приложения, вложенный класс @TestConfiguration используется дополнительно к основной конфигурации вашего приложения.

Обычно конфигурация теста, найденная @SpringBootTest, будет вашим основным @SpringBootApplication. В большинстве хорошо структурированных приложений этот класс конфигурации также будет включать метод main, используемый для запуска приложения.

Например, ниже представлен распространённый шаблон кода для типичного приложения Spring Boot:

В примере выше метод main не делает ничего, кроме делегирования вызова в SpringApplication.run. Однако возможно иметь более сложный метод main, который применяет настройки перед вызовом SpringApplication.run.

Например, вот приложение, которое изменяет режим баннера и задаёт дополнительные профили:

Поскольку настройки в методе main могут влиять на полученный ApplicationContext, возможно, вам также захочется использовать метод main для создания ApplicationContext, используемого в ваших тестах. По умолчанию, @SpringBootTest не будет вызывать ваш метод main, а вместо этого напрямую использует класс для создания ApplicationContext.

Если вы хотите изменить это поведение, вы можете изменить атрибут useMainMethod аннотации @SpringBootTest на UseMainMethod.ALWAYS или UseMainMethod.WHEN_AVAILABLE. При установке на ALWAYS тест завершится ошибкой, если не найден метод main. При установке на WHEN_AVAILABLE метод main будет использован, если он доступен, в противном случае будет использован стандартный механизм загрузки.

Например, следующий тест вызовет метод main класса MyApplication, чтобы создать ApplicationContext. Если главный метод устанавливает дополнительные профили, они будут активны при запуске ApplicationContext.

Если ваше приложение использует сканирование компонентов (например, если вы используете @SpringBootApplication или @ComponentScan), вы можете случайно обнаружить классы конфигурации верхнего уровня, созданные только для определённых тестов, которые подхватываются везде.

Как мы уже видели, @TestConfiguration может быть использован для внутреннего класса теста для настройки основной конфигурации. При размещении на классе верхнего уровня, @TestConfiguration указывает, что классы в src/test/java не должны подхватываться сканированием. Тогда вы можете импортировать этот класс явно, где он необходим, как показано в следующем примере:

Если ваше приложение ожидает аргументы, вы можете использовать @SpringBootTest для их инъекции с помощью атрибута args.

По умолчанию @SpringBootTest не запускает сервер, а вместо этого настраивает эмулированную среду для тестирования веб-точек входа.

С помощью Spring MVC, мы можем запросить наши веб-точки входа, используя MockMvc или WebTestClient, как показано в следующем примере:

С Spring WebFlux точками входа, вы можете использовать WebTestClient, как показано в следующем примере:

Если вам нужно запустить полностью работающий сервер, рекомендуется использовать случайные порты. Если вы используете @SpringBootTest(webEnvironment=WebEnvironment.RANDOM_PORT), доступный порт выбирается случайным образом каждый раз, когда запускается ваш тест.

Аннотация @LocalServerPort может быть использована для инъекции фактического используемого порта в ваш тест. Для удобства, тесты, которые нуждаются в выполнении REST-запросов к запущенному серверу, могут дополнительно @Autowire WebTestClient, который разрешает относительные ссылки к запущенному серверу и поставляется с отдельным API для проверки ответов, как показано в следующем примере:

Эта настройка требует spring-webflux в классе. Если вы не можете или не хотите добавлять webflux, Spring Boot также предоставляет TestRestTemplate возможность:

Для настройки компонента WebTestClient, настройте компонент WebTestClientBuilderCustomizer. Любые такие компоненты вызываются с помощью WebTestClient.Builder, используемого для создания WebTestClient.

Поскольку тестовая рамка кеширует контекст, JMX по умолчанию отключен, чтобы предотвратить регистрацию идентичных компонентов в одной и той же области. Если такому тесту нужен доступ к MBeanServer, рассмотрите возможность пометить его как изменённый:

Независимо от вашего classpath, реестры счетчиков, за исключением реестров в памяти, не настраиваются автоматически при использовании @SpringBootTest.

Если вам нужно экспортировать метрики в другой бэкенд в рамках интеграционного теста, отметьте его аннотацией @AutoConfigureObservability.

Независимо от вашего classpath, отслеживание не настраивается автоматически при использовании @SpringBootTest.

Если вам нужно отслеживание в рамках интеграционного теста, отметьте его аннотацией @AutoConfigureObservability.

При выполнении тестов иногда необходимо смоделировать определённые компоненты в контексте приложения. Например, у вас может быть фасад над какой-либо удалённой службой, которая недоступна во время разработки. Моделирование также может быть полезным, когда вы хотите смоделировать ошибки, которые могут быть трудно воспроизвести в реальной среде.

Spring Boot включает аннотацию @MockBean, которая может быть использована для определения модели Mockito для бинда внутри вашего ApplicationContext. Вы можете использовать аннотацию для добавления новых бинов или замены одного существующего определения бинда. Аннотация может быть использована напрямую на тестовых классах, на полях в вашем тесте или на @Configuration классах и полях. При использовании на поле экземпляр созданной модели также инжектируется. Модели бинов автоматически сбрасываются после каждого тестового метода.

Следующий пример заменяет существующий RemoteService бинд моделью:

Кроме того, вы можете использовать @SpyBean для обертывания любого существующего бинда с помощью модели Mockito spy. Смотрите Javadoc для получения полной информации.

Система автоконфигурации Spring Boot хорошо работает для приложений, но иногда может быть слишком сложной для тестов. Зачастую полезно загрузить только те части конфигурации, которые необходимы для тестирования "фрагмента" вашего приложения. Например, вы можете захотеть проверить, что контроллеры Spring MVC правильно отображают URL-адреса, и не хотите вовлекать вызовы к базе данных в эти тесты, или вы можете захотеть протестировать сущности JPA, и вас не интересует веб-слой при запуске этих тестов.

Модуль spring-boot-test-autoconfigure включает ряд аннотаций, которые можно использовать для автоматической конфигурации таких "фрагментов". Каждая из них работает аналогичным образом, предоставляя аннотацию @…​Test, которая загружает ApplicationContext, и одну или несколько аннотаций @AutoConfigure…​, которые можно использовать для настройки параметров автоконфигурации.

Для проверки корректности сериализации и десериализации объектов JSON вы можете использовать аннотацию @JsonTest. @JsonTest автоматически настраивает доступный поддерживаемый маппер JSON, который может быть одной из следующих библиотек:

Если вам нужно настроить элементы автоконфигурации, вы можете использовать аннотацию @AutoConfigureJsonTesters.

Spring Boot включает помощники на основе AssertJ, которые работают с библиотеками JSONAssert и JsonPath для проверки того, что JSON отображается как ожидается. Классы JacksonTester, GsonTester, JsonbTester и BasicJsonTester могут быть использованы для Jackson, Gson, Jsonb и строк соответственно. Любые вспомогательные поля в тестовом классе могут быть @Autowired при использовании @JsonTest. Следующий пример демонстрирует тестовый класс для Jackson:

Если вы используете помощники Spring Boot на основе AssertJ для проверки числового значения по заданному пути JSON, вы, возможно, не сможете использовать isEqualTo в зависимости от типа. Вместо этого вы можете использовать satisfies AssertJ для проверки того, что значение соответствует заданному условию. Например, следующий пример проверяет, что фактическое число является значением типа float, близким к 0.15 с отклонением в 0.01.

Для проверки корректной работы контроллеров Spring MVC используйте аннотацию @WebMvcTest. @WebMvcTest автоматически настраивает инфраструктуру Spring MVC и ограничивает сканирование бинов до @Controller, @ControllerAdvice, @JsonComponent, Converter, GenericConverter, Filter, HandlerInterceptor, WebMvcConfigurer, WebMvcRegistrations и HandlerMethodArgumentResolver. Регулярные бины @Component и @ConfigurationProperties не будут сканироваться при использовании аннотации @WebMvcTest. Аннотация @EnableConfigurationProperties может быть использована для включения бинов @ConfigurationProperties.

Часто @WebMvcTest ограничивается одним контроллером и используется в сочетании с @MockBean для предоставления имитирующих реализаций необходимых коллабораторов.

@WebMvcTest также автоматически настраивает MockMvc. Мок MVC предоставляет мощный способ быстрого тестирования контроллеров MVC без необходимости запуска полного HTTP-сервера.

Если вы используете HtmlUnit и Selenium, автоконфигурация также предоставляет бин HtmlUnit WebClient и/или бин Selenium WebDriver. Следующий пример использует HtmlUnit:

Если у вас Spring Security в classpath, @WebMvcTest также будет сканировать бины WebSecurityConfigurer. Вместо того, чтобы полностью отключать безопасность для таких тестов, вы можете использовать поддержку Spring Security. Подробнее о том, как использовать поддержку Spring Security MockMvc, можно найти в разделе howto.html.

Для проверки корректной работы контроллеров Spring WebFlux используйте аннотацию @WebFluxTest. @WebFluxTest автоматически настраивает инфраструктуру Spring WebFlux и ограничивает сканирование бинов до @Controller, @ControllerAdvice, @JsonComponent, Converter, GenericConverter, WebFilter и WebFluxConfigurer. Регулярные бины @Component и @ConfigurationProperties не будут сканироваться при использовании аннотации @WebFluxTest. @EnableConfigurationProperties может быть использован для включения бинов @ConfigurationProperties.

Часто @WebFluxTest ограничивается одним контроллером и используется в сочетании с аннотацией @MockBean для предоставления имитационных реализаций необходимых коллабораторов.

@WebFluxTest также автоматически настраивает WebTestClient, что предоставляет мощный способ быстрого тестирования контроллеров WebFlux без необходимости запуска полного HTTP-сервера.

Spring GraphQL предлагает специализированный модуль поддержки тестирования; вам нужно добавить его в свой проект:

Этот модуль тестирования поставляет GraphQlTester. Тестер широко используется в тестах, поэтому обязательно ознакомьтесь с его использованием. Существует GraphQlTester варианты, и Spring Boot будет автоматически настраивать их в зависимости от типа тестов:

Spring Boot помогает вам тестировать ваши Spring GraphQL контроллеры с помощью аннотации @GraphQlTest. @GraphQlTest автоматически настраивает инфраструктуру Spring GraphQL без участия транспорта или сервера. Это ограничивает сканируемые бин к @Controller, RuntimeWiringConfigurer, JsonComponent, Converter, GenericConverter, DataFetcherExceptionResolver, Instrumentation и GraphQlSourceBuilderCustomizer. Регулярные бин @Component и @ConfigurationProperties не сканируются при использовании аннотации @GraphQlTest. @EnableConfigurationProperties можно использовать для включения бинов @ConfigurationProperties.

Часто @GraphQlTest ограничивается набором контроллеров и используется в сочетании с аннотацией @MockBean для предоставления моковых реализаций необходимых коллабораторов.

@SpringBootTest тесты являются полными интеграционными тестами и включают весь проект. При использовании случайного или заданного порта настраивается живой сервер, и бин HttpGraphQlTester автоматически добавляется, так что вы можете использовать его для тестирования вашего сервера. При конфигурации среды MOCK вы также можете запросить бин HttpGraphQlTester, добавив аннотацию @AutoConfigureHttpGraphQlTester к вашему тестовому классу:

Вы можете использовать @DataCassandraTest для тестирования приложений Cassandra. По умолчанию он настраивает CassandraTemplate, сканирует классы @Table и настраивает репозитории Spring Data Cassandra. Регулярные бин @Component и @ConfigurationProperties не сканируются при использовании аннотации @DataCassandraTest. @EnableConfigurationProperties можно использовать для включения бинов @ConfigurationProperties. (Подробнее о работе с Cassandra в Spring Boot см. "data.html".)

Следующий пример демонстрирует типичную настройку для использования тестов Cassandra в Spring Boot:

Вы можете использовать @DataCouchbaseTest для тестирования приложений Couchbase. По умолчанию он настраивает CouchbaseTemplate или ReactiveCouchbaseTemplate, сканирует классы @Document и настраивает репозитории Spring Data Couchbase. Регулярные бин @Component и @ConfigurationProperties не сканируются при использовании аннотации @DataCouchbaseTest. @EnableConfigurationProperties можно использовать для включения бинов @ConfigurationProperties. (Подробнее о работе с Couchbase в Spring Boot см. "data.html" в этой главе.)

Следующий пример демонстрирует типичную настройку для использования тестов Couchbase в Spring Boot:

Вы можете использовать @DataElasticsearchTest для тестирования приложений Elasticsearch. По умолчанию он настраивает ElasticsearchRestTemplate, сканирует классы @Document и настраивает репозитории Spring Data Elasticsearch. Регулярные бин @Component и @ConfigurationProperties не сканируются при использовании аннотации @DataElasticsearchTest. @EnableConfigurationProperties можно использовать для включения бинов @ConfigurationProperties. (Подробнее о работе с Elasticsearch в Spring Boot см. "data.html" в этой главе.)

Следующий пример демонстрирует типичную настройку для использования тестов Elasticsearch в Spring Boot:

Вы можете использовать аннотацию @DataJpaTest для тестирования приложений JPA. По умолчанию она сканирует классы @Entity и настраивает репозитории Spring Data JPA. Если на пути к классу доступна встроенная база данных, она также настраивается. Запросы SQL по умолчанию регистрируются, если свойство spring.jpa.show-sql установлено в значение true. Это можно отключить, используя атрибут showSql аннотации.

Обычные @Component и @ConfigurationProperties бины не сканируются при использовании аннотации @DataJpaTest. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов.

По умолчанию тесты Data JPA транзакционные и откатываются в конце каждого теста. Подробности см. в соответствующем разделе документации Spring Framework. Если этого не требуется, вы можете отключить управление транзакциями для теста или для всего класса следующим образом:

Тесты Data JPA также могут инжектировать бин TestEntityManager, что предоставляет альтернативу стандартному JPA EntityManager, специально разработанному для тестов.

Также доступен JdbcTemplate, если вам это нужно. Следующий пример демонстрирует использование аннотации @DataJpaTest:

Встроенные базы данных в памяти обычно хорошо подходят для тестов, так как они быстры и не требуют установки. Однако, если вы предпочитаете запускать тесты против реальной базы данных, вы можете использовать аннотацию @AutoConfigureTestDatabase, как показано в следующем примере:

@JdbcTest аналогичен @DataJpaTest, но предназначен для тестов, которые требуют только DataSource и не используют Spring Data JDBC. По умолчанию он настраивает встроенную базу данных в памяти и JdbcTemplate. Обычные @Component и @ConfigurationProperties бины не сканируются при использовании аннотации @JdbcTest. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов.

По умолчанию JDBC-тесты транзакционные и откатываются в конце каждого теста. Подробности см. в соответствующем разделе документации Spring Framework. Если это не требуется, можно отключить управление транзакциями для теста или для всего класса следующим образом:

Если вы предпочитаете запускать тест против реальной базы данных, вы можете использовать аннотацию @AutoConfigureTestDatabase так же, как и для DataJpaTest. (См. "Автонастроенные тесты Data JPA".)

@DataJdbcTest аналогичен @JdbcTest, но предназначен для тестов, использующих репозитории Spring Data JDBC. По умолчанию он настраивает встроенную базу данных в памяти, JdbcTemplate и репозитории Spring Data JDBC. Только подклассы AbstractJdbcConfiguration сканируются при использовании аннотации @DataJdbcTest; обычные @Component и @ConfigurationProperties бины не сканируются. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов.

По умолчанию тесты Data JDBC транзакционные и откатываются в конце каждого теста. Подробности см. в соответствующем разделе документации Spring Framework. Если этого не требуется, можно отключить управление транзакциями для теста или для всего тестового класса, как показано в примере JDBC.

Если вы предпочитаете запускать тест против реальной базы данных, вы можете использовать аннотацию @AutoConfigureTestDatabase аналогично DataJpaTest. (См. "Автонастроенные тесты Data JPA".)

@DataR2dbcTest аналогичен @DataJdbcTest, но предназначен для тестов, использующих репозитории Spring Data R2DBC. По умолчанию он настраивает встроенную базу данных в памяти, R2dbcEntityTemplate и репозитории Spring Data R2DBC. Обычные @Component и @ConfigurationProperties бины не сканируются при использовании аннотации @DataR2dbcTest. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов.

По умолчанию тесты Data R2DBC не транзакционные.

Если вы предпочитаете запускать тест против реальной базы данных, вы можете использовать аннотацию @AutoConfigureTestDatabase аналогично DataJpaTest. (См. "Автонастроенные тесты Data JPA".)

Вы можете использовать @JooqTest аналогично @JdbcTest, но для тестов, связанных с jOOQ. Поскольку jOOQ сильно зависит от схемы на Java, соответствующей схеме базы данных, используется существующая DataSource. Если вы хотите заменить её встроенной базой данных, вы можете использовать @AutoConfigureTestDatabase для переопределения этих настроек. (Подробнее о работе с jOOQ в Spring Boot см. "data.html".) Обычные @Component и @ConfigurationProperties бины не сканируются при использовании аннотации @JooqTest. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов.

@JooqTest настраивает DSLContext. Следующий пример демонстрирует использование аннотации @JooqTest:

Тесты jOOQ по умолчанию транзакционные и откатываются в конце каждого теста. Если это не требуется, можно отключить управление транзакциями для теста или для всего тестового класса, как показано в примере JDBC.

Вы можете использовать @DataMongoTest для тестирования приложений MongoDB. По умолчанию он настраивает MongoTemplate, сканирует классы @Document и настраивает репозитории Spring Data MongoDB. Регулярные @Component и @ConfigurationProperties бины не сканируются, когда используется аннотация @DataMongoTest. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов. (Дополнительную информацию об использовании MongoDB с Spring Boot см. в "data.html".)

Следующий класс демонстрирует использование аннотации @DataMongoTest:

Вы можете использовать @DataNeo4jTest для тестирования приложений Neo4j. По умолчанию он сканирует классы @Node и настраивает репозитории Spring Data Neo4j. Регулярные @Component и @ConfigurationProperties бины не сканируются, когда используется аннотация @DataNeo4jTest. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов. (Дополнительную информацию об использовании Neo4J с Spring Boot см. в "data.html".)

Следующий пример показывает типичную настройку для использования тестов Neo4J в Spring Boot:

По умолчанию тесты данных Neo4j транзакционные и откатываются в конце каждого теста. Более подробную информацию см. в соответствующем разделе документации по Spring Framework. Если это не то, что вам нужно, вы можете отключить управление транзакциями для теста или для всего класса следующим образом:

Вы можете использовать @DataRedisTest для тестирования приложений Redis. По умолчанию он сканирует классы @RedisHash и настраивает репозитории Spring Data Redis. Регулярные @Component и @ConfigurationProperties бины не сканируются, когда используется аннотация @DataRedisTest. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов. (Дополнительную информацию об использовании Redis с Spring Boot см. в "data.html".)

Следующий пример показывает использование аннотации @DataRedisTest:

Вы можете использовать @DataLdapTest для тестирования приложений LDAP. По умолчанию он настраивает встроенный LDAP в памяти (если доступен), настраивает LdapTemplate, сканирует классы @Entry и настраивает репозитории Spring Data LDAP. Регулярные @Component и @ConfigurationProperties бины не сканируются, когда используется аннотация @DataLdapTest. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов. (Дополнительную информацию об использовании LDAP с Spring Boot см. в "data.html".)

Следующий пример показывает использование аннотации @DataLdapTest:

Встроенный LDAP в памяти обычно хорошо работает для тестов, так как он быстрый и не требует установки разработчиком. Однако, если вы предпочитаете выполнять тесты на реальном сервере LDAP, вы должны исключить встроенную автоконфигурацию LDAP, как показано в следующем примере:

Вы можете использовать аннотацию @RestClientTest для тестирования REST-клиентов. По умолчанию он автоматически настраивает поддержку Jackson, GSON и Jsonb, настраивает RestTemplateBuilder и добавляет поддержку MockRestServiceServer. Регулярные @Component и @ConfigurationProperties бины не сканируются при использовании аннотации @RestClientTest. @EnableConfigurationProperties можно использовать для включения @ConfigurationProperties бинов.

Конкретные бины, которые вы хотите протестировать, должны быть указаны с помощью атрибута value или components аннотации @RestClientTest, как показано в следующем примере:

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

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

Каждый срез предоставляет одну или несколько аннотаций @AutoConfigure…​, которые, в частности, определяют автоконфигурации, которые должны быть включены в качестве части среза. Дополнительные автоконфигурации можно добавить в тесты по отдельности, создав пользовательскую аннотацию @AutoConfigure…​ или добавив @ImportAutoConfiguration в тест, как показано в следующем примере:

В качестве альтернативы, дополнительные автоконфигурации можно добавить для любого использования аннотации среза, зарегистрировав их в файле, хранящемся в META-INF/spring, как показано в следующем примере:

В этом примере com.example.IntegrationAutoConfiguration включена для каждого теста, помеченного аннотацией @JdbcTest.

Если вы структурируете свой код разумным образом, ваш класс @SpringBootApplication по умолчанию используется в качестве конфигурации ваших тестов.

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

Предположим, что вы используете Spring Data MongoDB, полагаетесь на автоматическую конфигурацию для него и включили аудит. Вы можете определить свой класс @SpringBootApplication следующим образом:

Поскольку этот класс является исходной конфигурацией для теста, любой тестовый срез фактически пытается включить аудит Mongo, что определенно не то, что вам нужно. Рекомендуемый подход заключается в перемещении конфигурации, специфичной для области, в отдельный класс @Configuration на том же уровне, что и ваше приложение, как показано в следующем примере:

Тестовые срезы исключают классы @Configuration из сканирования. Например, для @WebMvcTest следующая конфигурация не будет включать заданный бин WebMvcConfigurer в контекст приложения, загруженный тестовым срезом:

Однако, конфигурация ниже приведет к загрузке настраиваемого WebMvcConfigurer тестовым срезом.

Еще одним источником путаницы является сканирование classpath. Предположим, что, хотя вы структурировали свой код разумным образом, вам нужно просканировать дополнительный пакет. Ваше приложение может иметь следующий код:

Это фактически переопределяет стандартную директиву сканирования компонентов с побочным эффектом сканирования этих двух пакетов независимо от выбранного среза. Например, тестовый срез может внезапно начать сканировать компоненты и пользовательские конфигурации вашего приложения. Опять же, перемещение пользовательской директивы в отдельный класс — хороший способ исправить эту проблему.

Spock 2.2 или более поздней версии можно использовать для тестирования приложения Spring Boot. Для этого добавьте зависимость от версии -groovy-4.0 модуля spock-spring Spock в ваш проект. spock-spring интегрирует фреймворк тестов Spring в Spock. Дополнительные сведения см. в документации модуля Spring для Spock.

Подключение к сервису — это соединение с любой удаленной службой. Автоконфигурация Spring Boot может использовать детали подключения к сервису и использовать их для установления соединения с удаленной службой. При этом данные подключения имеют приоритет над любыми свойствами конфигурации, связанными с подключением.

При использовании Testcontainers данные подключения могут быть автоматически созданы для сервиса, работающего в контейнере, путем аннотирования поля контейнера в классе тестов.

Благодаря @ServiceConnection, вышеуказанная настройка позволяет связанным с Neo4j компонентам приложения взаимодействовать с Neo4j, работающим внутри управляемого Testcontainers Docker контейнера. Это делается путем автоматического определения компонента Neo4jConnectionDetails, который затем используется автоконфигурацией Neo4j, переопределяя любые свойства конфигурации, связанные с подключением.

Аннотации подключений к сервисам обрабатываются классами ContainerConnectionDetailsFactory, зарегистрированными с помощью spring.factories. Класс ContainerConnectionDetailsFactory может создавать компонент ConnectionDetails на основе конкретного подкласса Container или имени образа Docker.

В JAR-файле spring-boot-testcontainers предоставляются следующие фабрики подключений к сервисам:

По умолчанию используется Container.getDockerImageName() для получения имени, используемого для поиска данных подключения. При использовании пользовательского образа Docker можно использовать атрибут name компонента @ServiceConnection для его переопределения.

Например, если у вас есть GenericContainer, использующий образ Docker registry.mycompany.com/mirror/myredis, вам нужно использовать @ServiceConnection(name="redis"), чтобы гарантировать создание RedisConnectionDetails.

Несколько более подробный, но и более гибкий вариант подключения к сервисам — это @DynamicPropertySource. Статический метод @DynamicPropertySource позволяет добавлять динамические значения свойств в среду Spring.

Вышеуказанная конфигурация позволяет связанным с Neo4j компонентам приложения взаимодействовать с Neo4j, работающим внутри управляемого Testcontainers Docker контейнера.

Помимо использования Testcontainers для интеграционных тестов, их также можно применять на этапе разработки. Такой подход позволяет разработчикам быстро запускать контейнеры для служб, от которых зависит приложение, исключая необходимость ручного развёртывания, например, баз данных. Использование Testcontainers таким образом обеспечивает функциональность, аналогичную Docker Compose, за исключением того, что конфигурация контейнера задаётся на Java, а не в YAML.

Чтобы использовать Testcontainers на этапе разработки, необходимо запустить ваше приложение, используя «тестовый» класспаф, а не «основной». Это позволит вам получить доступ ко всем объявленным тестовым зависимостям и предоставит естественное место для написания тестовой конфигурации.

Для создания запускаемого в тестовом режиме варианта вашего приложения, необходимо создать класс «Application» в каталоге src/test. Например, если ваше основное приложение находится в src/main/java/com/example/MyApplication.java, то вы должны создать src/test/java/com/example/TestMyApplication.java

Класс TestMyApplication может использовать метод SpringApplication.from(…​) для запуска реального приложения:

Вам также необходимо определить экземпляры Container, которые вы хотите запустить вместе с приложением. Для этого нужно убедиться, что модуль spring-boot-testcontainers добавлен в качестве зависимости test. После этого вы можете создать класс @TestConfiguration, который объявляет методы @Bean для контейнеров, которые вы хотите запустить.

Вы также можете аннотировать методы @Bean с помощью @ServiceConnection для создания ConnectionDetails бинов. Подробности поддерживаемых технологий см. в разделе соединений с сервисами выше.

Типичная конфигурация Testcontainers будет выглядеть так:

После определения конфигурации тестов, вы можете использовать метод with(…​) для подключения её к запуску ваших тестов:

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