Unit Testing Configuration Properties and Profiles

Overview

This skill provides patterns for unit testing @ConfigurationProperties bindings, environment-specific configurations, and property validation using JUnit 5. Covers testing property name mapping, type conversions, validation constraints, nested structures, and profile-specific configurations without full Spring context startup.

Key validation checkpoints:

• Property prefix matches between @ConfigurationProperties and test properties

• Validation triggers on @Validated classes with invalid values

• Type conversions work for Duration, DataSize, collections, and maps

When to Use

• Testing @ConfigurationProperties property binding

• Testing property name mapping and type conversions

• Validating configuration with @NotBlank , @Min , @Max , @Email constraints

• Testing environment-specific configurations (dev, prod)

• Testing nested property structures and collections

• Verifying default values when properties are not specified

• Fast configuration tests without Spring context startup

Instructions

• Set up test dependencies: Add spring-boot-starter-test and AssertJ dependencies

• Use ApplicationContextRunner: Test property bindings without starting full Spring context

• Define property prefixes: Ensure @ConfigurationProperties(prefix = "...") matches test property paths

• Test all property paths: Verify each property including nested structures and collections

• Test validation constraints: Use context.hasFailed() to verify @Validated properties reject invalid values

• Test type conversions: Verify Duration (30s ), DataSize (50MB ), collections, and maps convert correctly

• Test default values: Verify properties have correct defaults when not specified in test properties

• Test profile-specific configs: Use @Profile with ApplicationContextRunner for environment-specific configurations

• Test edge cases: Include empty strings, null values, and type mismatches

Troubleshooting flow:

• If properties don't bind → Check prefix matches (kebab-case to camelCase conversion)

• If validation doesn't trigger → Verify @Validated annotation is present

• If context fails to start → Check dependencies and @ConfigurationProperties class structure

Examples

Setup: Test Dependencies

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <scope>provided</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.assertj</groupId> <artifactId>assertj-core</artifactId> <scope>test</scope> </dependency>

Basic Pattern: Property Binding

@ConfigurationProperties(prefix = "app.security") @Data public class SecurityProperties { private String jwtSecret; private long jwtExpirationMs; private int maxLoginAttempts; private boolean enableTwoFactor; }

class SecurityPropertiesTest {

@Test void shouldBindPropertiesFromEnvironment() { new ApplicationContextRunner() .withPropertyValues( "app.security.jwtSecret=my-secret-key", "app.security.jwtExpirationMs=3600000", "app.security.maxLoginAttempts=5", "app.security.enableTwoFactor=true" ) .withBean(SecurityProperties.class) .run(context -> { SecurityProperties props = context.getBean(SecurityProperties.class); assertThat(props.getJwtSecret()).isEqualTo("my-secret-key"); assertThat(props.getJwtExpirationMs()).isEqualTo(3600000L); assertThat(props.getMaxLoginAttempts()).isEqualTo(5); assertThat(props.isEnableTwoFactor()).isTrue(); }); }

@Test void shouldUseDefaultValuesWhenPropertiesNotProvided() { new ApplicationContextRunner() .withPropertyValues("app.security.jwtSecret=key") .withBean(SecurityProperties.class) .run(context -> { SecurityProperties props = context.getBean(SecurityProperties.class); assertThat(props.getJwtSecret()).isEqualTo("key"); assertThat(props.getMaxLoginAttempts()).isZero(); }); } }

Validation Testing

@ConfigurationProperties(prefix = "app.server") @Data @Validated public class ServerProperties { @NotBlank private String host;

@Min(1) @Max(65535) private int port = 8080;

@Positive private int threadPoolSize; }

class ConfigurationValidationTest {

@Test void shouldFailValidationWhenHostIsBlank() { new ApplicationContextRunner() .withPropertyValues( "app.server.host=", "app.server.port=8080", "app.server.threadPoolSize=10" ) .withBean(ServerProperties.class) .run(context -> { assertThat(context).hasFailed() .getFailure() .hasMessageContaining("host"); }); }

@Test void shouldPassValidationWithValidConfiguration() { new ApplicationContextRunner() .withPropertyValues( "app.server.host=localhost", "app.server.port=8080", "app.server.threadPoolSize=10" ) .withBean(ServerProperties.class) .run(context -> { assertThat(context).hasNotFailed(); assertThat(context.getBean(ServerProperties.class).getHost()).isEqualTo("localhost"); }); } }

Type Conversion Testing

@ConfigurationProperties(prefix = "app.features") @Data public class FeatureProperties { private Duration cacheExpiry = Duration.ofMinutes(10); private DataSize maxUploadSize = DataSize.ofMegabytes(100); private List<String> enabledFeatures; private Map<String, String> featureFlags; }

class TypeConversionTest {

@Test void shouldConvertDurationFromString() { new ApplicationContextRunner() .withPropertyValues("app.features.cacheExpiry=30s") .withBean(FeatureProperties.class) .run(context -> { assertThat(context.getBean(FeatureProperties.class).getCacheExpiry()) .isEqualTo(Duration.ofSeconds(30)); }); }

@Test void shouldConvertCommaDelimitedList() { new ApplicationContextRunner() .withPropertyValues("app.features.enabledFeatures=feature1,feature2") .withBean(FeatureProperties.class) .run(context -> { assertThat(context.getBean(FeatureProperties.class).getEnabledFeatures()) .containsExactly("feature1", "feature2"); }); } }

For nested properties, profile-specific configurations, collection binding, and advanced validation patterns, see references/advanced-examples.md .

Best Practices

• Test all property bindings including nested structures and collections

• Test validation constraints for all @NotBlank , @Min , @Max , @Email , @Positive annotations

• Test both default and custom values to verify fallback behavior

• Use ApplicationContextRunner for fast context-free testing

• Test profile-specific configurations separately with @Profile

• Verify type conversions for Duration, DataSize, collections, and maps

• Test edge cases: empty strings, null values, type mismatches, out-of-range values

Constraints and Warnings

• Kebab-case to camelCase: Property app.my-property maps to myProperty in Java

• Loose binding: Spring Boot uses loose binding by default; use strict binding if needed

• @Validated required: Add @Validated annotation to enable constraint validation

• @ConstructorBinding : All parameters must be bindable when using constructor binding

• List indexing: Use [0] , [1] notation; ensure sequential indexing for lists

• Duration format: Accepts ISO-8601 (PT30S ) or simple syntax (30s , 1m , 2h )

• Context isolation: Each ApplicationContextRunner creates a new context with no shared state

• Profile activation: Use spring.profiles.active=profileName in withPropertyValues() for profile tests

Troubleshooting

Issue Cause Solution

Properties not binding Prefix mismatch Verify @ConfigurationProperties(prefix="...") matches property paths

Validation not triggered Missing @Validated

Add @Validated annotation to configuration class

Context fails to start Missing dependencies Ensure spring-boot-starter-test is in test scope

Nested properties null Inner class missing Use @Data on nested classes or provide getters/setters

Collection binding fails Wrong indexing Use [0] , [1] notation, not (0) , (1)