unit-test-bean-validation

Unit Testing Jakarta Bean Validation

Overview

This skill provides executable patterns for unit testing Jakarta Bean Validation annotations and custom validators using JUnit 5. Covers built-in constraints (@NotNull, @Email, @Min, @Max, @Size), custom @Constraint implementations, cross-field validation, and validation groups. Tests run in isolation without Spring context.

When to Use

• Writing unit tests for Jakarta Bean Validation or JSR-380 constraints
• Testing custom @Constraint validators and constraint violation messages
• Testing bean validation logic in DTOs and request objects
• Verifying cross-field validation (e.g., password matching)
• Testing conditional validation with validation groups
• Fast validation tests without Spring Boot context

Instructions

1. Add dependencies: Include jakarta.validation-api and hibernate-validator in test scope
2. Create base test class: Build Validator once in @BeforeEach using Validation.buildDefaultValidatorFactory()
3. Test valid cases first: Verify objects pass without violations
4. Test invalid cases: Assert constraint violations include correct property path and message
5. Extract violation details: Use getPropertyPath(), getMessage(), getInvalidValue()
6. Test custom validators: See references/custom-validators.md for patterns
7. Use parameterized tests: Test multiple inputs efficiently with @ParameterizedTest
8. Group validation tests: Use validation groups for conditional rules (see references/advanced-patterns.md)

Examples

Maven Setup

<dependency>
  <groupId>jakarta.validation</groupId>
  <artifactId>jakarta.validation-api</artifactId

Common Test Setup

Testing Basic Constraints

Testing Custom Validators

For custom constraint patterns, see references/custom-validators.md:

• Creating @Constraint annotations
• Implementing ConstraintValidator
• Cross-field validation (password matching)
• Stateless validator best practices

Testing Validation Groups

For validation groups and parameterized tests, see references/advanced-patterns.md:

• Defining validation group interfaces
• Conditional validation with groups parameter
• @ParameterizedTest with @ValueSource and @CsvSource
• Debugging failed validation tests

Best Practices

• Test both valid and invalid: Every constraint needs both passing and failing test cases
• Assert violation details: Verify property path, message, and constraint type
• Test edge cases: null, empty string, whitespace-only, boundary values
• Keep validators stateless: Custom validators must not maintain state
• Use clear messages: Constraint messages should be user-friendly
• Group related tests: Extend BaseValidationTest to share validator setup
• Test error messages: Ensure messages match requirements

Common Pitfalls

• Forgetting to test null values (most constraints ignore null by default)
• Not verifying the property path in constraint violations
• Testing validation at service/controller level instead of unit level
• Creating overly complex custom validators
• Missing @NotNull for mandatory fields combined with other constraints

Constraints and Warnings

• Null handling: Most constraints ignore null by default — combine @NotNull with other constraints for mandatory fields
• Thread safety: Validator instances are thread-safe and can be shared
• Message localization: Test with different locales if i18n is required
• Cascading validation: Use @Valid on nested objects for recursive validation
• Custom validators: Must be stateless and return true for null values
• Test isolation: Validation unit tests should not depend on Spring context or database

Troubleshooting

ValidatorFactory not found: Ensure jakarta.validation-api and hibernate-validator are on test classpath.

Custom validator not invoked: Verify @Constraint(validatedBy = YourValidator.class) annotation is correct.

Null values pass validation: This is expected behavior — constraints ignore null unless @NotNull is present.

Wrong violation count: Use hasSize() to verify exact count, check all fields in the object.

Property path incorrect: Ensure the field, not the getter, has the constraint annotation.

References

• Jakarta Bean Validation Spec
• Hibernate Validator
• Custom validators and cross-field validation: references/custom-validators.md
• Validation groups and parameterized tests: references/advanced-patterns.md