Learning Test One: Validate a single, primitive attribute

Time to write our first (domain) object and validate something. We'll do this using the TestNG framework to create a tiny test driver showcasing how the most basic validation API calls interact.

Let's code the domain object

package de.lightful.jsr303.examples.basic;

import javax.validation.constraints.Min;

public class Person {

  @Min( 2000 )
  private int yearlyIncome;

  public Person(int yearlyIncome) {
    this.yearlyIncome = yearlyIncome;
  }

  public int getYearlyIncome() {
    return yearlyIncome;
  }
}

You probably notice the @Min(2000) annotation prepended to the yearlyIncome attribute. It tells the validation framework that a constraint applies to this attribute. It's meaning is: the minimum allowed value for this attribute is 2000. Lower values are invalid. JSR 303 provides a number of standard constraints which live in package javax.validation.constraints.* We're going to have a look at them later.

Now for the test driver...

package de.lightful.jsr303.examples.basic;

import static org.fest.assertions.Assertions.assertThat;

import java.util.Set;
import javax.validation.ConstraintViolation;
import javax.validation.Validation;
import javax.validation.Validator;
import javax.validation.ValidatorFactory;
import org.testng.annotations.BeforeMethod;
import org.testng.annotations.Test;

@Test
public class PersonTest {

  private Validator validator;

  @BeforeMethod
  private void setUp() {
    ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
    validator = factory.getValidator();
  }

  public void validationFailsForIncomeBelow2000() {
    Person peter = new Person(1999);
    Set<ConstraintViolation<Person>> violations = validator.validate(peter);

    assertThat(violations.size()).as("Number of violations").isEqualTo(1);
  }
}

The setUp() method demonstrates how to obtain an instance of the validator runtime. The central API starting point API is class Validation, which is capable of creating a ValidatorFactory we can then use to create the actual validator.

The single test method simply creates a person with an income too low and validates it using the validate(...) method, passing it the object to be validated. Next, we assert that (ehm... well, that's actually a fluent assertion API - since it's fluent I'm just asking myself, why should I rephrase it in plain english if its written there in plain english? Go have a look at FEST-Assert ;-)

Pitfall: missing SLF4J dependency

Trying to run the above test, we'll receive a beautiful error message:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Reason: Hibernate Validator (HV) uses the well-known Simple Logging Facade For Java, but leaves the decision which of the possible logging frameworks to use as implementation for the facade up to the "client" of Hibernate Validator (that's us, in this case). Peeking into HV's pom.xml shows us this:

    <!-- ...  -->
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId>
      <version>1.5.6</version>
      <scope>runtime</scope>
      <optional>true</optional>
    </dependency>
    <!-- ...  -->

There is a runtime dependency on the Log4J-based SLF4J implementation, but this dependency is optional, allowing us to substitute it if needed, plus maven will not complain if we omit it from the classpath. To actually use it, we have to declare it explicitly in our parent pom.xml:

  <!-- ... -->
  <dependencies>
   <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-validator</artifactId>
      <version>4.0.2.GA</version>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-log4j12</artifactId>
      <version>1.5.6</version>
      <scope>runtime</scope>
    </dependency>
    <!-- ... -->

Another gotcha: make sure to use the right version of slf4j-log4j12. They cannot be mixed and matched, but have to be compatible. SLF4j will complain if they don't.

Running the test...

...yields no surprises. There is exactly one violation. Notice however that the validator returns a Set<ConstraintViolation<Person>>, which we will have a look at on the following page.