public abstract Class AbstractOptionalAssert<SELF extends AbstractOptionalAssert<SELF, VALUE>, VALUE>

Verifies that the actual java.util.Optional contains the given value (alias of hasValue(Object)).

Assertion will pass :

 assertThat(Optional.of("something")).contains("something");
assertThat(Optional.of(10)).contains(10);

 assertThat(Optional.of("something")).contains("something else");
assertThat(Optional.of(20)).contains(10);

Parameters

expectedValue:VALUE

the expected value inside the java.util.Optional.

Returns:SELF

this assertion object.

Verifies that the actual Optional contains a value that is an instance of the argument.

Assertions will pass:

 assertThat(Optional.of("something")).containsInstanceOf(String.class)
                                    .containsInstanceOf(Object.class);

assertThat(Optional.of(10)).containsInstanceOf(Integer.class);

 assertThat(Optional.of("something")).containsInstanceOf(Integer.class);

Parameters

clazz:Class<?>

the expected class of the value inside the Optional.

Returns:SELF

this assertion object.

Verifies that the actual java.util.Optional contains the instance given as an argument (i.e. it must be the same instance).

Assertion will pass :

 String someString = "something";
assertThat(Optional.of(someString)).containsSame(someString);

// Java will create the same 'Integer' instance when boxing small ints
assertThat(Optional.of(10)).containsSame(10);

 // not even equal:
assertThat(Optional.of("something")).containsSame("something else");
assertThat(Optional.of(20)).containsSame(10);

// equal but not the same:
assertThat(Optional.of(new String("something"))).containsSame(new String("something"));
assertThat(Optional.of(new Integer(10))).containsSame(new Integer(10));

Parameters

expectedValue:VALUE

the expected value inside the java.util.Optional.

Returns:SELF

this assertion object.

Call flatMap on the Optional under test, assertions chained afterwards are performed on the Optional resulting from the flatMap call.

Examples:

 Function<String, Optional<String>> UPPER_CASE_OPTIONAL_STRING =
      s -> s == null ? Optional.empty() : Optional.of(s.toUpperCase());

// assertions succeed
assertThat(Optional.of("something")).contains("something")
                                    .flatMap(UPPER_CASE_OPTIONAL_STRING)
                                    .contains("SOMETHING");

assertThat(Optional.<String>empty()).flatMap(UPPER_CASE_OPTIONAL_STRING)
                                    .isEmpty();

assertThat(Optional.<String>ofNullable(null)).flatMap(UPPER_CASE_OPTIONAL_STRING)
                                             .isEmpty();

// assertion fails
assertThat(Optional.of("something")).flatMap(UPPER_CASE_OPTIONAL_STRING)
                                    .contains("something");

Parameters

<U>

the type wrapped in the Optional after the flatMap operation.

mapper:Function<? super VALUE, Optional<U>>

the Function to use in the flatMap operation.

Returns:AbstractOptionalAssert<?, U>

a new AbstractOptionalAssert for assertions chaining on the flatMap of the Optional.

Annotations

@CheckReturnValue

Exceptions

AssertionError:

if the actual Optional is null.

Since

3.6.0

Verifies that the actual Optional is not null and not empty and returns an Object assertion that allows chaining (object) assertions on the optional value.

Note that it is only possible to return Object assertions after calling this method due to java generics limitations.

Example:

 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);
TolkienCharacter sam = new TolkienCharacter("Sam", 38, null);

// assertion succeeds since all frodo's fields are set
assertThat(Optional.of(frodo)).get().hasNoNullFieldsOrProperties();

// assertion does not succeed because sam does not have its race set
assertThat(Optional.of(sam)).get().hasNoNullFieldsOrProperties();

Returns:AbstractObjectAssert<?, VALUE>

a new AbstractObjectAssert for assertions chaining on the value of the Optional.

Annotations

@CheckReturnValue

Exceptions

AssertionError:

• if the actual Optional is null.
• if the actual Optional is empty.

Since

3.9.0

See Also

get(InstanceOfAssertFactory)

Verifies that the actual Optional is not null and not empty and returns an new assertion instance to chain assertions on the optional value.

The assertFactory parameter allows to specify an InstanceOfAssertFactory, which is used to get the assertions narrowed to the factory type.

Wrapping the given InstanceOfAssertFactory with Assertions#as(InstanceOfAssertFactory) makes the assertion more readable.

Example:

 // assertion succeeds
assertThat(Optional.of("frodo")).get(as(InstanceOfAssertFactories.STRING)).startsWith("fro");

// assertion does not succeed because frodo is not an Integer
assertThat(Optional.of("frodo")).get(as(InstanceOfAssertFactories.INTEGER)).isZero();

Parameters

<ASSERT>

the type of the resulting Assert

assertFactory:InstanceOfAssertFactory<?, ASSERT>

the factory which verifies the type and creates the new Assert

Returns:ASSERT

a new narrowed Assert instance for assertions chaining on the value of the Optional

Annotations

@CheckReturnValue

Exceptions

NullPointerException:

if the given factory is null

AssertionError:

• if the actual Optional is null
• if the actual Optional is empty

Since

3.14.0

Verifies that the actual java.util.Optional contains the given value (alias of contains(Object)).

Assertion will pass :

 assertThat(Optional.of("something")).hasValue("something");
assertThat(Optional.of(10)).contains(10);

 assertThat(Optional.of("something")).hasValue("something else");
assertThat(Optional.of(20)).contains(10);

Parameters

expectedValue:VALUE

the expected value inside the java.util.Optional.

Returns:SELF

this assertion object.

Verifies that the actual java.util.Optional contains a value and gives this value to the given java.util.function.Consumer for further assertions. Should be used as a way of deeper asserting on the containing object, as further requirement(s) for the value.

Assertions will pass :

 // one requirement
assertThat(Optional.of(10)).hasValueSatisfying(i -> { assertThat(i).isGreaterThan(9); });

// multiple requirements
assertThat(Optional.of(someString)).hasValueSatisfying(s -> {
  assertThat(s).isEqualTo("something");
  assertThat(s).startsWith("some");
  assertThat(s).endsWith("thing");
}); 

 assertThat(Optional.of("something")).hasValueSatisfying(s -> {
    assertThat(s).isEqualTo("something else");
  });

// fail because optional is empty, there is no value to perform assertion on
assertThat(Optional.empty()).hasValueSatisfying(o -> {});

Parameters

requirement:Consumer<VALUE>

to further assert on the object contained inside the java.util.Optional.

Returns:SELF

this assertion object.

Verifies that the actual Optional contains a value which satisfies the given Condition.

Examples:

 Condition<TolkienCharacter> isAnElf = new Condition<>(character -> character.getRace() == ELF, "an elf");

TolkienCharacter legolas = new TolkienCharacter("Legolas", 1000, ELF);
TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);

// assertion succeeds
assertThat(Optional.of(legolas)).hasValueSatisfying(isAnElf);

// assertion fails
assertThat(Optional.of(frodo)).hasValueSatisfying(isAnElf);

Parameters

condition:Condition<? super VALUE>

the given condition.

Returns:SELF

this assertion object.

Exceptions

AssertionError:

• if the actual Optional is null or empty.
• if the actual value does not satisfy the given condition.

NullPointerException:

if the given condition is null.

Since

3.6.0

Verifies that the actual java.util.Optional is empty.

Assertion will pass :

 assertThat(Optional.empty()).isEmpty();

 assertThat(Optional.of("something")).isEmpty();

Returns:SELF

this assertion object.

Verifies that there is a value present in the actual java.util.Optional, it's an alias of isPresent().

Assertion will pass :

 assertThat(Optional.of("something")).isNotEmpty();

 assertThat(Optional.empty()).isNotEmpty();

Returns:SELF

this assertion object.

Verifies that the actual java.util.Optional is empty (alias of isEmpty()).

Assertion will pass :

 assertThat(Optional.empty()).isNotPresent();

 assertThat(Optional.of("something")).isNotPresent();

Returns:SELF

this assertion object.

Verifies that there is a value present in the actual java.util.Optional.

Assertion will pass :

 assertThat(Optional.of("something")).isPresent();

 assertThat(Optional.empty()).isPresent();

Returns:SELF

this assertion object.

Call map on the Optional under test, assertions chained afterwards are performed on the Optional resulting from the map call.

Examples:

 // assertions succeed
assertThat(Optional.<String>empty()).map(String::length)
                                    .isEmpty();

assertThat(Optional.of("42")).contains("42")
                             .map(String::length)
                             .contains(2);

// assertion fails
assertThat(Optional.of("42")).map(String::length)
                             .contains(3);

Parameters

<U>

the type wrapped in the Optional after the map operation.

mapper:Function<? super VALUE, ? extends U>

the Function to use in the map operation.

Returns:AbstractOptionalAssert<?, U>

a new AbstractOptionalAssert for assertions chaining on the map of the Optional.

Annotations

@CheckReturnValue

Exceptions

AssertionError:

if the actual Optional is null.

Since

3.6.0

Revert to standard comparison for incoming assertion Optional value checks.

This method should be used to disable a custom comparison strategy set by calling usingValueComparator(Comparator).

Returns:SELF

this assertion object.

Annotations

@CheckReturnValue

 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);
TolkienCharacter frodoClone = new TolkienCharacter("Frodo", 33, HOBBIT);

// frodo and frodoClone are equals when doing a field by field comparison.
assertThat(Optional.of(frodo)).get().usingRecursiveComparison()
                              .isEqualTo(frodoClone);

Use field/property by field/property comparison (including inherited fields/properties) instead of relying on actual type A equals method to compare the Optional value's object for incoming assertion checks. Private fields are included but this can be disabled using Assertions#setAllowExtractingPrivateFields(boolean).

This can be handy if equals method of the Optional value's object to compare does not suit you.

Example:

 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);
TolkienCharacter frodoClone = new TolkienCharacter("Frodo", 33, HOBBIT);

// Fail if equals has not been overridden in TolkienCharacter as equals default implementation only compares references
assertThat(Optional.of(frodo)).contains(frodoClone);

// frodo and frodoClone are equals when doing a field by field comparison.
assertThat(Optional.of(frodo)).usingFieldByFieldValueComparator().contains(frodoClone);

Returns:SELF

this assertion object.

Annotations

@Deprecated

@CheckReturnValue

@SuppressWarnings:DeprecatedIsStillUsed, deprecation

Overrides org.assertj.core.api.AbstractAssert.usingRecursiveAssertion.

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(Optional.of(pramodSadalage)).usingRecursiveAssertion()
                                       .allFieldsSatisfy(field -> field != null); 

In case one or more fields in the object graph fails the predicate test, the entire assertion will fail. Failing fields will be listed in the failure report using a JSON path-ish notation.

Returns:RecursiveAssertionAssert

A new instance of RecursiveAssertionAssert built with a default RecursiveAssertionConfiguration.

Annotations

@Override

Overrides org.assertj.core.api.AbstractAssert.usingRecursiveAssertion.

The same as usingRecursiveAssertion(), but this method allows the developer to pass in an explicit recursion configuration. This configuration gives fine-grained control over what to include in the recursion, such as:

• Exclusion of fields that are null
• Exclusion of fields by path
• Exclusion of fields by type
• Exclusion of primitive fields
• Inclusion of Java Class Library types in the recursive execution
• Treatment of java.util.Collection and array objects
• Treatment of java.util.Map objects
• Treatment of Optional and primitive Optional objects

Please refer to the documentation of RecursiveAssertionConfiguration.Builder for more details.

Parameters

recursiveAssertionConfiguration:RecursiveAssertionConfiguration

The recursion configuration described above.

Returns:RecursiveAssertionAssert

A new instance of RecursiveAssertionAssert built with a default RecursiveAssertionConfiguration.

Annotations

@Override

Overrides org.assertj.core.api.AbstractAssert.usingRecursiveComparison.

Enable using a recursive field by field comparison strategy when calling the chained RecursiveComparisonAssert,

Example:

 public class Person {
  String name;
  boolean hasPhd;
}

public class Doctor {
 String name;
 boolean hasPhd;
}

Doctor drSheldon = new Doctor("Sheldon Cooper", true);
Person sheldon = new Person("Sheldon Cooper", true);

Optional<Doctor> doctor = Optional.of(drSheldon);
Optional<Person> person = Optional.of(sheldon);

// assertion succeeds as both maps contains equivalent items.
assertThat(doctor).usingRecursiveComparison()
                  .isEqualTo(person);

// assertion fails because leonard names are different.
drSheldon.setName("Sheldon Kooper");
assertThat(doctor).usingRecursiveComparison()
                  .isEqualTo(person);

The default recursive comparison behavior is configured as follows:

• different types of iterable can be compared by default as in the example, this can be turned off by calling withStrictTypeChecking.
• overridden equals methods are used in the comparison (unless stated otherwise - see https://assertj.github.io/doc/#assertj-core-recursive-comparison-ignoring-equals)
• the following types are compared with these comparators:
  • java.lang.Double: DoubleComparator with precision of 1.0E-15
  • java.lang.Float: FloatComparator with precision of 1.0E-6
  • any comparators previously registered with AbstractIterableAssert#usingComparatorForType(Comparator, Class)

Returns:RecursiveComparisonAssert<?>

a new RecursiveComparisonAssert instance

Annotations

@Override

@Beta

See Also

RecursiveComparisonConfiguration

Overrides org.assertj.core.api.AbstractAssert.usingRecursiveComparison.

Same as usingRecursiveComparison() but allows to specify your own RecursiveComparisonConfiguration.

Parameters

recursiveComparisonConfiguration:RecursiveComparisonConfiguration

the RecursiveComparisonConfiguration used in the chained isEqualTo assertion.

Returns:RecursiveComparisonAssert<?>

a new RecursiveComparisonAssert instance built with the given RecursiveComparisonConfiguration.

Annotations

@Override

Use given custom comparator instead of relying on actual type A equals method to compare the Optional value's object for incoming assertion checks.

Custom comparator is bound to assertion instance, meaning that if a new assertion is created, it will use default comparison strategy.

Examples :

 TolkienCharacter frodo = new TolkienCharacter("Frodo", 33, HOBBIT);
TolkienCharacter frodoClone = new TolkienCharacter("Frodo", 33, HOBBIT);

// Fail if equals has not been overridden in TolkienCharacter as equals default implementation only compares references
assertThat(Optional.of(frodo)).contains(frodoClone);

// frodo and frodoClone are equals when doing a field by field comparison.
assertThat(Optional.of(frodo)).usingValueComparator(new FieldByFieldComparator()).contains(frodoClone);

Parameters

customComparator:Comparator<? super VALUE>

the comparator to use for incoming assertion checks.

Returns:SELF

this assertion object.

Annotations

@CheckReturnValue

Exceptions

NullPointerException:

if the given comparator is null.