public Class RecursiveAssertionAssert

Asserts that the given predicate is met for all fields of the object under test recursively (but not the object itself).

For example if the object under test is an instance of class A, A has a B field and B a C field then the assertion checks A's B field and B's C field and all C's fields.

The recursive algorithm employs cycle detection, so object graphs with cyclic references can safely be asserted over without causing looping.

This method enables recursive asserting using default configuration, which means all fields of all objects have the java.util.function.Predicate applied to them (including primitive fields), no fields are excluded, but:

• The recursion does not enter into Java Class Library types (java.*, javax.*)
• The java.util.function.Predicate is applied to java.util.Collection and array elements (but not the collection/array itself)
• The java.util.function.Predicate is applied to java.util.Map values but not the map itself or its keys
• The java.util.function.Predicate is applied to java.util.Optional and primitive optional values

You can change how the recursive assertion deals with arrays, collections, maps and optionals, see:

• RecursiveAssertionAssert#withCollectionAssertionPolicy(RecursiveAssertionConfiguration.CollectionAssertionPolicy) for collections and arrays
• RecursiveAssertionAssert#withMapAssertionPolicy(RecursiveAssertionConfiguration.MapAssertionPolicy) for maps
• RecursiveAssertionAssert#withOptionalAssertionPolicy(RecursiveAssertionConfiguration.OptionalAssertionPolicy) for optionals

It is possible to assert several predicates over the object graph in a row.

The classes used in recursive asserting are not thread safe. Care must be taken when running tests in parallel not to run assertions over object graphs that are being shared between tests.

Example:

 class Author {
  String name;
  String email;
  List<Book> books = new ArrayList<>();

  Author(String name, String email) {
    this.name = name;
    this.email = email;
  }
}

class Book {
  String title;
  Author[] authors;

  Book(String title, Author[] authors) {
    this.title = title;
    this.authors = authors;
  }
}

Author pramodSadalage = new Author("Pramod Sadalage", "[email protected]");
Author martinFowler = new Author("Martin Fowler", "[email protected]");
Author kentBeck = new Author("Kent Beck", "[email protected]");

Book noSqlDistilled = new Book("NoSql Distilled", new Author[] {pramodSadalage, martinFowler});
pramodSadalage.books.add(noSqlDistilled);
martinFowler.books.add(noSqlDistilled);

Book refactoring = new Book("Refactoring", new Author[] {martinFowler, kentBeck});
martinFowler.books.add(refactoring);
kentBeck.books.add(refactoring);

// assertion succeeds
assertThat(pramodSadalage).usingRecursiveAssertion()
                          .allFieldsSatisfy(field -> field != null); 

Parameters

predicate:Predicate<Object>

The predicate that is recursively applied to all the fields in the object tree of which actual is the root.

Returns:RecursiveAssertionAssert

this assertions object

Exceptions

AssertionError:

if one or more fields as described above fail the predicate test.

Asserts that none of the fields of the object under test graph (i.e. recursively getting the fields) are null (but not the object itself).

This is a convenience method for a common test, and it is equivalent to allFieldsSatisfy(field -> field != null).

Example:

 class Author {
  String name;
  String email;
  List<Book> books = new ArrayList<>();

  Author(String name, String email) {
    this.name = name;
    this.email = email;
  }
}

class Book {
  String title;
  Author[] authors;

  Book(String title, Author[] authors) {
    this.title = title;
    this.authors = authors;
  }
}

Author pramodSadalage = new Author("Pramod Sadalage", "[email protected]");
Author martinFowler = new Author("Martin Fowler", "[email protected]");
Author kentBeck = new Author("Kent Beck", "[email protected]");

Book noSqlDistilled = new Book("NoSql Distilled", new Author[]{pramodSadalage, martinFowler});
pramodSadalage.books.add(noSqlDistilled);
martinFowler.books.add(noSqlDistilled);

Book refactoring = new Book("Refactoring", new Author[] {martinFowler, kentBeck});
martinFowler.books.add(refactoring);
kentBeck.books.add(refactoring);

// assertion succeeds
assertThat(pramodSadalage).usingRecursiveAssertion()
                          .hasNoNullFields(); 

Returns:RecursiveAssertionAssert

this assertions object

Exceptions

AssertionError:

if one or more fields as described above are null.

Makes the recursive assertion to ignore all null fields.

 class Person {
  String name;
  String occupation;
  Address address;
}

class Address {
  int number;
  String street;
}

Person sherlock = new Person("Sherlock", "Detective");
sherlock.address = null;

// assertion succeeds as address field is ignored
assertThat(noName).usingRecursiveAssertion()
                  .ignoringAllNullFields()
                  .allFieldsSatisfy(field -> field instanceof String);

// assertion fails as address, address.number and address.street fields are not evaluated as String, street because it's null.
assertThat(sherlock).usingRecursiveAssertion()
                    .allFieldsSatisfy(field -> field instanceof String);

Returns:RecursiveAssertionAssert

this RecursiveAssertionAssert to chain other methods.

Makes the recursive assertion to ignore the specified fields in the object under test.

When a field is ignored, all its fields are ignored too.

Example:

 class Person {
  String name;
  String occupation;
  int age;
  Address address = new Address();
}

class Address {
  int number;
  String street;
}

Person sherlock = new Person("Sherlock", "Detective", 60);
sherlock.address.street = "Baker Street";
sherlock.address.number = 221;

// assertion succeeds because Person has only String fields except for address and age (address fields are ignored)
assertThat(sherlock).usingRecursiveAssertion()
                    .ignoringFields("address", "age")
                    .allFieldsSatisfy(field -> field instanceof String);

// assertion fails because of age, address and address.number fields
assertThat(sherlock).usingRecursiveAssertion()
                    .allFieldsSatisfy(field -> field instanceof String);

Parameters

fieldsToIgnore:String[]

the fields to ignore in the object under test.

Returns:RecursiveAssertionAssert

this RecursiveAssertionAssert to chain other methods.

Makes the recursive assertion to ignore the fields matching the specified regexes in the object under test.

When a field is ignored, all its fields are ignored too.

Example:

 class Person {
  String name;
  String occupation;
  int age;
  Address address = new Address();
}

class Address {
  int number;
  String street;
}

Person sherlock = new Person("Sherlock", "Detective", 60);
sherlock.address.street = "Baker Street";
sherlock.address.number = 221;

// assertion succeeds because Person has only String fields except for address and age (address fields are ignored)
assertThat(sherlock).usingRecursiveAssertion()
                    .ignoringFieldsMatchingRegexes("ad.*", "ag.")
                    .allFieldsSatisfy(field -> field instanceof String);

// assertion fails because of age and address fields (address.number is ignored)
assertThat(sherlock).usingRecursiveAssertion()
                    .ignoringFieldsMatchingRegexes(".*ber")
                    .allFieldsSatisfy(field -> field instanceof String);

Parameters

regexes:String[]

regexes used to ignore fields in the assertion.

Returns:RecursiveAssertionAssert

this RecursiveAssertionAssert to chain other methods.

Makes the recursive assertion to ignore the object under test fields of the given types. The fields are ignored if their types exactly match one of the ignored types, for example if a field is a subtype of an ignored type it is not ignored.

If some object under test fields are null it is not possible to evaluate their types and thus these fields are not ignored.

When a field is ignored, all its fields are ignored too.

Example:

 class Person {
  String name;
  String occupation;
  Address address = new Address();
}

class Address {
  int number;
  String street;
}

Person sherlock = new Person("Sherlock", "Detective");
sherlock.address.street = "Baker Street";
sherlock.address.number = 221;

// assertion succeeds because Person has only String fields except for address  (address fields are ignored)
assertThat(sherlock).usingRecursiveAssertion()
                    .ignoringFieldsOfTypes(Address.class)
                    .allFieldsSatisfy(field -> field instanceof String);

// assertion fails because of address and address.number fields
assertThat(sherlock).usingRecursiveAssertion()
                    .allFieldsSatisfy(field -> field instanceof String);

Parameters

typesToIgnore:Class<?>[]

the types we want to ignore in the object under test fields.

Returns:RecursiveAssertionAssert

this RecursiveAssertionAssert to chain other methods.

Make the recursive assertion not to run the Predicate over the primitive fields of an object in an object graph, by default asserting over primitives is enabled.

For example, consider the following class:

 class Example {
   public int primitiveField;
   public String objectField;
 } 

By default, the assertion being applied recursively will be applied to primitiveField and to objectField. If ignoring primitives it set to true, the assertion will only be applied to objectField.

If you elect to assert over primitives then it is your own responsibility as a developer to ensure that your Predicate can handle (boxed) primitive arguments.

Returns:RecursiveAssertionAssert

this RecursiveAssertionAssert to chain other methods.

Makes the recursive assertion to use the specified RecursiveAssertionConfiguration.CollectionAssertionPolicy.

See RecursiveAssertionConfiguration.CollectionAssertionPolicy for the different possible policies, by default RecursiveAssertionConfiguration.CollectionAssertionPolicy#ELEMENTS_ONLY is used.

Parameters

collectionAssertionPolicy:RecursiveAssertionConfiguration.CollectionAssertionPolicy

the RecursiveAssertionConfiguration.CollectionAssertionPolicy to use.

Returns:RecursiveAssertionAssert

this RecursiveAssertionAssert to chain other methods.

Defines how objects are introspected in the recursive assertion.

Default to DefaultRecursiveAssertionIntrospectionStrategy that introspects all fields (including inherited ones).

Parameters

introspectionStrategy:RecursiveAssertionIntrospectionStrategy

the RecursiveAssertionIntrospectionStrategy to use

Returns:RecursiveAssertionAssert

this RecursiveAssertionAssert to chain other methods.

Makes the recursive assertion to use the specified RecursiveAssertionConfiguration.MapAssertionPolicy.

See RecursiveAssertionConfiguration.MapAssertionPolicy for the different possible policies, by default RecursiveAssertionConfiguration.MapAssertionPolicy#MAP_VALUES_ONLY is used.

Parameters

mapAssertionPolicy:RecursiveAssertionConfiguration.MapAssertionPolicy

the RecursiveAssertionConfiguration.MapAssertionPolicy to use.

Returns:RecursiveAssertionAssert

this RecursiveAssertionAssert to chain other methods.

Makes the recursive assertion to use the specified RecursiveAssertionConfiguration.OptionalAssertionPolicy.

See RecursiveAssertionConfiguration.OptionalAssertionPolicy for the different possible policies, by default RecursiveAssertionConfiguration.OptionalAssertionPolicy#OPTIONAL_VALUE_ONLY is used.

Parameters

optionalAssertionPolicy:RecursiveAssertionConfiguration.OptionalAssertionPolicy

the RecursiveAssertionConfiguration.OptionalAssertionPolicy to use.

Returns:RecursiveAssertionAssert

this RecursiveAssertionAssert to chain other methods.