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", "[email protected]", 25);
    assertThat(validator.validate(user)).isEmpty();
  }

  @Test
  void shouldFailWhenNameIsNull() {
    UserDto user = new UserDto(null, "[email protected]", 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", "[email protected]", -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 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
• how to use unit-test-bean-validation
  CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity

  How to use unit-test-bean-validation on Cursor

  AI-first code editor with Composer

  1

  Prerequisites

  Before installing skills in Cursor, ensure your development environment meets these requirements:

  • ›Cursor installed and configured on your development machine
  • ›Node.js version 16.0+ with npm package manager (verify with node --version)
  • ›Active project directory or workspace where you want to add unit-test-bean-validation

  2

  Execute installation command

  Execute the skills CLI command in your project's root directory to begin installation:

  $npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-bean-validationcopy

  The skills CLI fetches unit-test-bean-validation from GitHub repository giuseppe-trisciuoglio/developer-kit and configures it for Cursor.

  3

  Select Cursor when prompted

  The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:

  ◆ Which agents do you want to install to?

  │

  │ ── Universal (.agents/skills) ── always included ────

  │ • Amp

  │ • Antigravity

  │ • Cline

  │ • Codex

  │ ●Cursor(selected)

  │ • Cursor

  │ • Windsurf

  4

  Verify installation

  Confirm successful installation by checking the skill directory location:

  .cursor/skills/unit-test-bean-validation

  Reload or restart Cursor to activate unit-test-bean-validation. Access the skill through slash commands (e.g., /unit-test-bean-validation) or your agent's skill management interface.

  ⚠

  Security & Verification Notice

  We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.

  Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.

  Additional Resources

  ›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?