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.

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

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

The class we want to make assertion on is TolkienCharacter :

// getter/setter not shown for brievety
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.

// 1 - Remember to 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.
  /**
   * Creates a new </code>{@link TolkienCharacterAssert}</code> to make assertions on actual TolkienCharacter.
   * @param actual the TolkienCharacter we want to make assertions on.
   */
  public TolkienCharacterAssert(TolkienCharacter actual) {
    super(actual, TolkienCharacterAssert.class);
  }

  // 3 - A fluent entry point to your specific assertion class
  // the other option here is to gather all your specific assertions entry point to a class inehriting from Assertions
  // thus this class will be your oonly entry poiny to all Fest assertions and YOURS.
  // see MyProjectAssertions for an example.
  /**
   * An entry point for TolkienCharacterAssert to follow Fest standard <code>assertThat()</code> statements.<br>
   * With a static import, one's can write directly : <code>assertThat(frodo).hasName("Frodo");</code>
   * @param actual the TolkienCharacter we want to make assertions on.
   * @return a new </code>{@link TolkienCharacterAssert}</code>
   */
  public static TolkienCharacterAssert assertThat(TolkienCharacter actual) {
    return new TolkienCharacterAssert(actual);
  }

  // 4 - a specific assertion !
  /**
   * Verifies that the actual TolkienCharacter's name is equal to the given one.
   * @param name the given name to compare the actual TolkienCharacter's name to.
   * @return this assertion object.
   * @throws AssertionError - if the actual TolkienCharacter's name is not equal to the given one.
   */
  public TolkienCharacterAssert hasName(String name) {
    // check that actual TolkienCharacter we want to make assertions on is not null.
    isNotNull();

    // TODO : EASE WRITING NEW ASSERTIONS
    // we overrides the default error message with a more explicit one
    String errorMessage = format("Expected character's name to be <%s> but was <%s>", name, actual.getName());

    // option 1 : raw assertion
    if (!actual.getName().equals(name)) { throw new AssertionError(errorMessage); }

    // option 2 : use of other Fest assertions (integrate better with custom comparator triggered by usingComparator)
    WritableAssertionInfo info = new WritableAssertionInfo();
    info.overridingErrorMessage(errorMessage);
    Objects.instance().assertEqual(info, actual.getName(), name);

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

  // 4 - another specific assertion !
  /**
   * Verifies that the actual TolkienCharacter's age is equal to the given one.
   * @param age the given age to compare the actual TolkienCharacter's age to.
   * @return this assertion object.
   * @throws AssertionError - if the actual TolkienCharacter's age is not equal to the given one.
   */
  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
    WritableAssertionInfo info = new WritableAssertionInfo();
    info.overridingErrorMessage(format("Expected character's age to be <%s> but was <%s>", age, actual.getAge()));
    Objects.instance().assertEqual(info, actual.getAge(), age);

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