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.

If you have a lot of classes you want to have assertions for, consider generating assertions.

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 providing 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);
  }
}

Generating specific assertions with fest assertions generator

We have written an assertion generator that takes classes or packages as input and generate the corresponding specific assertion classes (for all classes in specified packages). For example, if you have a Person class with an address property, it will generate hasAddress assertion as part of PersonAssert assertion class.

It comes with a maven plugin you can easily use in your maven build or in a one shot command.

Once assertions classes are generated, you can move them in source control and enrich them with the assertions the generator would not have been able to guess and generate.

You can also use eclipse assertion generator plugin, which is able generate assertions for a specific class (one at a time).