org.assertj.core.api

Class AbstractObjectAssert<S extends AbstractObjectAssert<S,A>,A>

java.lang.Object

org.assertj.core.api.AbstractAssert<S,A>

org.assertj.core.api.AbstractObjectAssert<S,A>

Type Parameters:

S - the "self" type of this assertion class. Please read "Emulating 'self types' using Java Generics to simplify fluent API implementation" for more details.

A - the type of the "actual" value.

All Implemented Interfaces:

Assert<S,A>, Descriptable<S>, ExtensionPoints<S,A>

Direct Known Subclasses:

AbstractComparableAssert, ObjectAssert

public abstract class AbstractObjectAssert<S extends AbstractObjectAssert<S,A>,A>
extends AbstractAssert<S,A>

Base class for all implementations of assertions for Objects.

Author:

Yvonne Wang, Alex Ruiz, Nicolas François, Mikhail Mazursky, Joel Costigliola, Libor Ondrusek

Field Summary

Fields inherited from class org.assertj.core.api.AbstractAssert

actual, info, myself

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractObjectAssert(A actual, Class<?> selfType)

Method Summary

Methods

Modifier and Type	Method and Description
AbstractObjectArrayAssert<?,Object>	extracting(String... propertiesOrFields) Extract the values of given fields/properties from the object under test into an array, this new array becoming the object under test.
S	hasFieldOrProperty(String name) Assert that the actual object has the specified field or property.
S	hasFieldOrPropertyWithValue(String name, Object value) Assert that the actual object has the specified field or property with the given value.
S	isEqualToComparingFieldByField(Object other) Assert that actual object is equal to the given object based on a property/field by property/field comparison (including inherited ones).
S	isEqualToComparingOnlyGivenFields(Object other, String... propertiesOrFieldsUsedInComparison) Assert that the actual object is equal to the given one using a property/field by property/field comparison on the given properties/fields only (fields can be inherited fields or nested fields).
S	isEqualToIgnoringGivenFields(Object other, String... propertiesOrFieldsToIgnore) Assert that the actual object is equal to the given one by comparing their properties/fields except for the given ones (inherited ones are taken into account).
S	isEqualToIgnoringNullFields(Object other) Assert that the actual object is equal to the given one by comparing actual's properties/fields with other's not null properties/fields only (including inherited ones).

Methods inherited from class org.assertj.core.api.AbstractAssert

as, as, asList, asString, describedAs, describedAs, descriptionText, doesNotHave, doesNotHaveSameClassAs, equals, failWithMessage, getWritableAssertionInfo, has, hashCode, hasSameClassAs, hasToString, inBinary, inHexadecimal, is, isEqualTo, isExactlyInstanceOf, isIn, isIn, isInstanceOf, isInstanceOfAny, isNot, isNotEqualTo, isNotExactlyInstanceOf, isNotIn, isNotIn, isNotInstanceOf, isNotInstanceOfAny, isNotNull, isNotOfAnyClassIn, isNotSameAs, isNull, isOfAnyClassIn, isSameAs, overridingErrorMessage, usingComparator, usingDefaultComparator, withFailMessage, withThreadDumpOnError

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractObjectAssert

protected AbstractObjectAssert(A actual,
                    Class<?> selfType)

Method Detail

isEqualToIgnoringNullFields

public S isEqualToIgnoringNullFields(Object other)

Assert that the actual object is equal to the given one by comparing actual's properties/fields with other's not null properties/fields only (including inherited ones).

It means that if an actual field is not null and the corresponding field in other is null, this field will be ignored in comparison, but the opposite will make assertion fail (null field in actual, not null in other) as the field is used in the performed comparison and the values differ.

Note that comparison is not recursive, if one of the field is an Object, it will be compared to the other field using its equals method.

If an object has a field and a property with the same name, the property value will be used over the field.

Private fields are used in comparison but this can be disabled using Assertions.setAllowComparingPrivateFields(boolean), if disabled only accessible fields values are compared, accessible fields include directly accessible fields (e.g. public) or fields with an accessible getter.

The objects to compare can be of different types but the properties/fields used in comparison must exist in both, for example if actual object has a name String field, it is expected other object to also have one.

Example:

 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);
 TolkienCharacter mysteriousHobbit = new TolkienCharacter(null, 33, HOBBIT);
 
 // Null fields in other/expected object are ignored, the mysteriousHobbit has null name thus name is ignored
 assertThat(frodo).isEqualToIgnoringNullFields(mysteriousHobbit); // OK
 
 // ... but the lenient equality is not reversible !
 assertThat(mysteriousHobbit).isEqualToIgnoringNullFields(frodo); // FAIL

Parameters:

other - the object to compare actual to.

Throws:

NullPointerException - if the actual or other object is null.

AssertionError - if the actual and the given object are not lenient equals.

IntrospectionError - if one of actual's field to compare can't be found in the other object.

isEqualToComparingOnlyGivenFields

public S isEqualToComparingOnlyGivenFields(Object other,
                                  String... propertiesOrFieldsUsedInComparison)

Assert that the actual object is equal to the given one using a property/field by property/field comparison on the given properties/fields only (fields can be inherited fields or nested fields). This can be handy if equals implementation of objects to compare does not suit you.

Note that comparison is not recursive, if one of the field is an Object, it will be compared to the other field using its equals method.

If an object has a field and a property with the same name, the property value will be used over the field.

Private fields are used in comparison but this can be disabled using Assertions.setAllowComparingPrivateFields(boolean), if disabled only accessible fields values are compared, accessible fields include directly accessible fields (e.g. public) or fields with an accessible getter.

The objects to compare can be of different types but the properties/fields used in comparison must exist in both, for example if actual object has a name String field, it is expected the other object to also have one.

Example:

 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);
 TolkienCharacter sam = new TolkienCharacter("Sam", 38, HOBBIT);
 
 // frodo and sam both are hobbits, so they are equals when comparing only race
 assertThat(frodo).isEqualToComparingOnlyGivenFields(sam, "race"); // OK
 
 // they are also equals when comparing only race name (nested field).
 assertThat(frodo).isEqualToComparingOnlyGivenFields(sam, "race.name"); // OK
 
 // ... but not when comparing both name and race
 assertThat(frodo).isEqualToComparingOnlyGivenFields(sam, "name", "race"); // FAIL

Parameters:

other - the object to compare actual to.

propertiesOrFieldsUsedInComparison - properties/fields used in comparison.

Throws:

NullPointerException - if the actual or other is null.

AssertionError - if the actual and the given objects are not equals property/field by property/field on given fields.

IntrospectionError - if one of actual's property/field to compare can't be found in the other object.

IntrospectionError - if a property/field does not exist in actual.

isEqualToIgnoringGivenFields

public S isEqualToIgnoringGivenFields(Object other,
                             String... propertiesOrFieldsToIgnore)

Assert that the actual object is equal to the given one by comparing their properties/fields except for the given ones (inherited ones are taken into account). This can be handy if equals implementation of objects to compare does not suit you.

Note that comparison is not recursive, if one of the property/field is an Object, it will be compared to the other field using its equals method.

If an object has a field and a property with the same name, the property value will be used over the field.

Private fields are used in comparison but this can be disabled using Assertions.setAllowComparingPrivateFields(boolean), if disabled only accessible fields values are compared, accessible fields include directly accessible fields (e.g. public) or fields with an accessible getter.

The objects to compare can be of different types but the properties/fields used in comparison must exist in both, for example if actual object has a name String field, it is expected the other object to also have one.

Example:

 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);
 TolkienCharacter sam = new TolkienCharacter("Sam", 38, HOBBIT);
 
 // frodo and sam are equals when ignoring name and age since the only remaining field is race which they share as HOBBIT.
 assertThat(frodo).isEqualToIgnoringGivenFields(sam, "name", "age"); // OK
 
 // ... but they are not equals if only age is ignored as their names differ.
 assertThat(frodo).isEqualToIgnoringGivenFields(sam, "age"); // FAIL

Parameters:

other - the object to compare actual to.

propertiesOrFieldsToIgnore - ignored properties/fields to ignore in comparison.

Throws:

NullPointerException - if the actual or given object is null.

AssertionError - if the actual and the given objects are not equals property/field by property/field after ignoring given fields.

IntrospectionError - if one of actual's property/field to compare can't be found in the other object.

isEqualToComparingFieldByField

public S isEqualToComparingFieldByField(Object other)

Assert that actual object is equal to the given object based on a property/field by property/field comparison (including inherited ones). This can be handy if equals implementation of objects to compare does not suit you.

Note that comparison is not recursive, if one of the field is an Object, it will be compared to the other field using its equals method.

If an object has a field and a property with the same name, the property value will be used over the field.

Private fields are used in comparison but this can be disabled using Assertions.setAllowComparingPrivateFields(boolean), if disabled only accessible fields values are compared, accessible fields include directly accessible fields (e.g. public) or fields with an accessible getter.

The objects to compare can be of different types but the properties/fields used in comparison must exist in both, for example if actual object has a name String field, it is expected the other object to also have one.

Example:

 // equals not overridden in TolkienCharacter 
 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);
 TolkienCharacter frodoClone = new TolkienCharacter("Frodo", 33, HOBBIT);
 
 // Fail as equals compares object references
 assertThat(frodo).isEqualsTo(frodoClone);
 
 // frodo and frodoClone are equals when doing a field by field comparison.
 assertThat(frodo).isEqualToComparingFieldByField(frodoClone);

Parameters:

other - the object to compare actual to.

Throws:

AssertionError - if the actual object is null.

AssertionError - if the actual and the given objects are not equals property/field by property/field.

IntrospectionError - if one of actual's property/field to compare can't be found in the other object.

hasFieldOrProperty

public S hasFieldOrProperty(String name)

Assert that the actual object has the specified field or property.

Private fields are matched by default but this can be changed by calling Assertions.setAllowExtractingPrivateFields(false).

Example:

 public class TolkienCharacter {

   private String name;
   private int age;
   // constructor omitted
      
   public String getName() {
     return this.name;
   }
 }

 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33);
 
 // assertions will pass :
 assertThat(frodo).hasFieldOrProperty("name")
                  .hasFieldOrProperty("age"); // private field are matched by default
         
 // assertions will fail :
 assertThat(frodo).hasFieldOrProperty("not_exists");
 assertThat(frodo).hasFieldOrProperty(null);
 // disable looking for private fields
 Assertions.setAllowExtractingPrivateFields(false);
 assertThat(frodo).hasFieldOrProperty("age"); 

Parameters:

name - the field/property name to check

Throws:

AssertionError - if the actual object is null.

IllegalArgumentException - if name is null.

AssertionError - if the actual object has not the given field/property

hasFieldOrPropertyWithValue

public S hasFieldOrPropertyWithValue(String name,
                            Object value)

Assert that the actual object has the specified field or property with the given value.

Private fields are matched by default but this can be changed by calling Assertions.setAllowExtractingPrivateFields(false).

Example:

 public class TolkienCharacter {
   private String name;
   private int age;
   // constructor omitted

   public String getName() {
     return this.name;
   }
 }

 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33);
 TolkienCharacter noname = new TolkienCharacter(null, 33);

 // assertions will pass :
 assertThat(frodo).hasFieldOrProperty("name", "Frodo");
 assertThat(frodo).hasFieldOrProperty("age", 33);
 assertThat(noname).hasFieldOrProperty("name", null);

 // assertions will fail :
 assertThat(frodo).hasFieldOrProperty("name", "not_equals"); 
 assertThat(frodo).hasFieldOrProperty(null, 33);             
 assertThat(frodo).hasFieldOrProperty("age", null);          
 assertThat(noname).hasFieldOrProperty("name", "Frodo");
 // disable extracting private fields
 Assertions.setAllowExtractingPrivateFields(false);
 assertThat(frodo).hasFieldOrProperty("age", 33); 

Parameters:

name - the field/property name to check

value - the field/property expected value

Throws:

AssertionError - if the actual object is null.

IllegalArgumentException - if name is null.

AssertionError - if the actual object has not the given field/property

AssertionError - if the actual object has the given field/property but not with the expected value

See Also:

hasFieldOrProperty(java.lang.String)

extracting

public AbstractObjectArrayAssert<?,Object> extracting(String... propertiesOrFields)

Extract the values of given fields/properties from the object under test into an array, this new array becoming the object under test.

If you extract "id", "name" and "email" fields/properties then the array will contain the id, name and email values of the object under test, you can then perform array assertions on the extracted values.

Nested fields/properties are supported, specifying "adress.street.number" is equivalent to get the value corresponding to actual.getAdress().getStreet().getNumber()

Private fields can be extracted unless you call Assertions.setAllowExtractingPrivateFields(false).

Example:

 // Create frodo, setting its name, age and Race fields (Race having a name field)
 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);
 
 // let's verify Frodo's name, age and race name:
 assertThat(frodo).extracting("name", "age", "race.name")
                  .containsExactly("Frodo", 33, "Hobbit");

A property with the given name is looked for first, if it doesn't exist then a field with the given name is looked for, if the field is not accessible (i.e. does not exist) an IntrospectionError is thrown.

Note that the order of extracted property/field values is consistent with the iteration order of the array under test.

Parameters:

propertiesOrFields - the properties/fields to extract from the initial array under test

Returns:

a new assertion object whose object under test is the array containing the extracted properties/fields values

Throws:

IntrospectionError - if one of the given name does not match a field or property