Class AssertionFailureBuilder

java.lang.Object
org.junit.jupiter.api.AssertionFailureBuilder
@API(status=STABLE, since="5.9") public class AssertionFailureBuilder extends Object
Builder for AssertionFailedErrors.

Using this builder ensures consistency in how failure message are formatted within JUnit Jupiter and for custom user-defined assertions.

Since:
5.9
See Also:

  • Method Details

    • assertionFailure

      public static AssertionFailureBuilder assertionFailure()
      Create a new AssertionFailureBuilder.

    • message

      public AssertionFailureBuilder message(@Nullable Object message)
      Set the user-defined message of the assertion.

      The message may be passed as a Supplier or plain String. If any other type is passed, it is converted to String as per StringUtils.nullSafeToString(Object).

      Parameters:
      message - the user-defined failure message; may be null
      Returns:
      this builder for method chaining

    • reason

      public AssertionFailureBuilder reason(@Nullable String reason)
      Set the reason why the assertion failed.
      Parameters:
      reason - the failure reason; may be null
      Returns:
      this builder for method chaining

    • cause

      public AssertionFailureBuilder cause(@Nullable Throwable cause)
      Set the cause of the assertion failure.
      Parameters:
      cause - the failure cause; may be null
      Returns:
      this builder for method chaining

    • expected

      public AssertionFailureBuilder expected(@Nullable Object expected)
      Set the expected value of the assertion.
      Parameters:
      expected - the expected value; may be null
      Returns:
      this builder for method chaining

    • actual

      public AssertionFailureBuilder actual(@Nullable Object actual)
      Set the actual value of the assertion.
      Parameters:
      actual - the actual value; may be null
      Returns:
      this builder for method chaining

    • includeValuesInMessage

      public AssertionFailureBuilder includeValuesInMessage(boolean includeValuesInMessage)
      Set whether to include the actual and expected values in the generated failure message.
      Parameters:
      includeValuesInMessage - whether to include the actual and expected values
      Returns:
      this builder for method chaining

    • trimStacktrace

      @API(status=EXPERIMENTAL, since="6.1") public AssertionFailureBuilder trimStacktrace(@Nullable Class<?> target)
      Set target to trim the stacktrace to.

      Unless retainStackTraceElements(int) is set all stacktrace elements before the last element from target are trimmed.

      Parameters:
      target - class to trim from the stacktrace
      Returns:
      this builder for method chaining

    • retainStackTraceElements

      @API(status=EXPERIMENTAL, since="6.1") public AssertionFailureBuilder retainStackTraceElements(int retainStackTraceElements)
      Set depth to trim the stacktrace to. Defaults to 1.

      If trimStacktrace(Class) was set, all but retainStackTraceElements - 1 stacktrace elements before the last element from target are removed. If retainStackTraceElements is zero, all elements including those from target are trimmed.

      Parameters:
      retainStackTraceElements - depth of trimming, must be non-negative
      Returns:
      this builder for method chaining

    • buildAndThrow

      public void buildAndThrow() throws AssertionFailedError
      Build the AssertionFailedError and throw it.
      Throws:
      AssertionFailedError - always

    • build

      public AssertionFailedError build()
      Build the AssertionFailedError without throwing it.
      Returns:
      the built assertion failure