Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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
@ConfigurationPropertiesand test properties - Validation triggers on
@Validatedclasses with invalid values - Type conversions work for Duration, DataSize, collections, and maps
When to Use
- Testing
@ConfigurationPropertiesproperty binding - Testing property name mapping and type conversions
- Validating configuration with
@NotBlank,@Min,@Max,@Emailconstraints - 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-testand 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@Validatedproperties 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
@ProfilewithApplicationContextRunnerfor 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
@Validatedannotation is present - If context fails to start → Check dependencies and
@ConfigurationPropertiesclass structure
Examples
Setup: Test Dependencies
xml
<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
java
@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
java
@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
java
@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,@Positiveannotations - 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-propertymaps tomyPropertyin Java - Loose binding: Spring Boot uses loose binding by default; use strict binding if needed
- `@Validated` required: Add
@Validatedannotation 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
ApplicationContextRunnercreates a new context with no shared state - Profile activation: Use
spring.profiles.active=profileNameinwithPropertyValues()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) |
