Creating specific assertions

(to main page)

Creating its own assertions is simple : create a class inheriting from AbstractAssert and add your custom assertions method.
To be easy to use, you should also add a static method assertThat to provide an handy entry point to your new assertion class.

Note that we plan to write an assertion generator that would take a class and generate the corresponding specific assertion class (stay tuned).

Creating your own assertion class

Let's see how to do that on an example !

The example is taken from fest-examples and more specifically in TolkienCharacterAssert.java..

The class we want to make assertion on is TolkienCharacter :

// getter/setter not shown for brevity
public class TolkienCharacter {
  private String name;
  private Race race;
  private int age;
}

We define TolkienCharacterAssert by inheriting from AbstractAssert and specifying the generic parameters, first is the class itself (needed for assertion chaining) and second is the class we want to make assert on : TolkienCharacter.

Inherits from AbstractAssert will provide you all the basic assertions (isEqualTo, isNull, ...).

// javadoc omitted for brevity
// 1 - inherits from AbstractAssert !
public class TolkienCharacterAssert extends AbstractAssert<TolkienCharacterAssert, TolkienCharacter> {

  // 2 - Write a constructor to build your assertion class from the object you want make assertions on.
  public TolkienCharacterAssert(TolkienCharacter actual) {
    super(actual, TolkienCharacterAssert.class);
  }

  // 3 - A fluent entry point to your specific assertion class, use it with static import.
  public static TolkienCharacterAssert assertThat(TolkienCharacter actual) {
    return new TolkienCharacterAssert(actual);
  }

  // 4 - a specific assertion !
  public TolkienCharacterAssert hasName(String name) {
    // check that actual TolkienCharacter we want to make assertions on is not null.
    isNotNull();

    // use of existing Fest assertions but replacing the error message (format specifier are supported)
    Assertions.assertThat(actual.getName())
        .overridingErrorMessage("Expected character's name to be <%s> but was <%s>", name, actual.getName())
        .isEqualTo(name);

    // another option : throwing directly an assertion error if the expected condition is not met
    String errorMessage = format("Expected character's name to be <%s> but was <%s>", name, actual.getName());
    if (!actual.getName().equals(name)) { throw new AssertionError(errorMessage); }

    return this; // return the current assertion for method chaining
  }

  // 4 - another specific assertion !
  public TolkienCharacterAssert hasAge(int age) {
    // check that actual TolkienCharacter we want to make assertions on is not null.
    isNotNull();

    // we overrides the default error message with a more explicit one
    Assertions.assertThat(actual.getAge())
        .overridingErrorMessage("Expected character's age to be <%s> but was <%s>", age, actual.getAge())
        .isEqualTo(age);
    
    return this; // return the current assertion for method chaining
  }
}

Providing a single entry for all assertions : yours + fest ones

It's easy :

1. Create a class inheriting from org.fest.assertions.api.Assertions.
2. Add assertThat static method proivding entry point to your own assertion :

Example taken from MyProjectAssertions.java in fest-examples :

// extending make all standard Fest assertions available.
public class MyProjectAssertions extends Assertions { 

  // add the custom assertions related to MyProject  
  public static TolkienCharacterAssert assertThat(TolkienCharacter actual) {
    return new TolkienCharacterAssert(actual);
  }
}