/unit-test-bean-validation

name: unit-test-bean-validation
description: Provides patterns for unit testing Jakarta Bean Validation (JSR-380), including @Valid, @NotNull, @Min, @Max, @Email constraints with Hibernate Validator. Generates custom validator tests, constraint violation assertions, validation groups, and parameterized validation tests. Validates data integrity logic without Spring context. Use when writing validation tests, bean validation tests, or testing custom constraint validators.
allowed-tools: Read, Write, Bash, Glob, Grep

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>
</dependency>
<dependency>
  <groupId>org.hibernate.validator</groupId>
  <artifactId>hibernate-validator</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <scope>test</scope>
</dependency>

Common Test Setup

import jakarta.validation.*;
import jakarta.validation.ConstraintViolation;
import jakarta.validation.path.Path;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import static org.assertj.core.api.Assertions.*;

class BaseValidationTest {
  protected Validator validator;

  @BeforeEach
  void setUpValidator() {
    validator = Validation.buildDefaultValidatorFactory().getValidator();
  }
}

Testing Basic Constraints

class UserDtoTest extends BaseValidationTest {

  @Test
  void shouldPassValidationWithValidUser() {
    UserDto user = new UserDto("Alice", "alice@example.com", 25);
    assertThat(validator.validate(user)).isEmpty();
  }

  @Test
  void shouldFailWhenNameIsNull() {
    UserDto user = new UserDto(null, "alice@example.com", 25);
    assertThat(validator.validate(user))
      .extracting(ConstraintViolation::getMessage)
      .contains("must not be blank");
  }

  @Test
  void shouldFailWhenEmailIsInvalid() {
    UserDto user = new UserDto("Alice", "invalid-email", 25);
    Set<ConstraintViolation<UserDto>> violations = validator.validate(user);
    assertThat(violations)
      .extracting(ConstraintViolation::getPropertyPath)
      .extracting(Path::toString)
      .contains("email");
  }

  @Test
  void shouldFailWhenAgeIsBelowMinimum() {
    UserDto user = new UserDto("Alice", "alice@example.com", -1);
    assertThat(validator.validate(user))
      .extracting(ConstraintViolation::getMessage)
      .contains("must be greater than or equal to 0");
  }

  @Test
  void shouldFailWhenMultipleConstraintsViolated() {
    UserDto user = new UserDto(null, "invalid", -5);
    assertThat(validator.validate(user)).hasSize(3);
  }
}

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