= Assertions

JUnit Jupiter comes with many of the assertion methods that JUnit 4 has and adds a few
that lend themselves well to being used with Java 8 lambdas. All JUnit Jupiter assertions
are `static` methods in the `{Assertions}` class.

Assertion methods optionally accept the assertion message as their third parameter, which
can be either a `String` or a `Supplier<String>`.

When using a `Supplier<String>` (e.g., a lambda expression), the message is evaluated
lazily. This can provide a performance benefit, especially if message construction is
complex or time-consuming, as it is only evaluated when the assertion fails.

[source,java,indent=0]
----
include::example$java/example/AssertionsDemo.java[tags=user_guide]
----

[[preemptive-timeouts]]
[WARNING]
.Preemptive Timeouts with `assertTimeoutPreemptively()`
====
The various `assertTimeoutPreemptively()` methods in the `Assertions` class execute
the provided `executable` or `supplier` in a different thread than that of the calling
code. This behavior can lead to undesirable side effects if the code that is executed
within the `executable` or `supplier` relies on `java.lang.ThreadLocal` storage.

One common example of this is the transactional testing support in the Spring Framework.
Specifically, Spring's testing support binds transaction state to the current thread (via
a `ThreadLocal`) before a test method is invoked. Consequently, if an `executable` or
`supplier` provided to `assertTimeoutPreemptively()` invokes Spring-managed components
that participate in transactions, any actions taken by those components will not be rolled
back with the test-managed transaction. On the contrary, such actions will be committed to
the persistent store (e.g., relational database) even though the test-managed transaction
is rolled back.

Similar side effects may be encountered with other frameworks that rely on
`ThreadLocal` storage.
====

[[kotlin]]
== Kotlin Assertion Support

JUnit Jupiter also comes with a few assertion methods that lend themselves well to being
used in https://kotlinlang.org/[Kotlin]. All JUnit Jupiter Kotlin assertions are top-level
functions in the `org.junit.jupiter.api` package.

[source,kotlin,indent=0]
----
include::example$kotlin/example/KotlinAssertionsDemo.kt[tags=user_guide]
----

[[third-party]]
== Third-party Assertion Libraries

Even though the assertion facilities provided by JUnit Jupiter are sufficient for many
testing scenarios, there are times when more power and additional functionality such as
_matchers_ are desired or required. In such cases, the JUnit team recommends the use of
third-party assertion libraries such as {AssertJ}, {Hamcrest}, {Truth}, etc. Developers
are therefore free to use the assertion library of their choice.

For example, the combination of _matchers_ and a fluent API can be used to make
assertions more descriptive and readable. However, JUnit Jupiter's `{Assertions}` class
does not provide an
https://junit.org/junit4/javadoc/latest/org/junit/Assert.html#assertThat[`assertThat()`]
method like the one found in JUnit 4's `org.junit.Assert` class which accepts a Hamcrest
https://junit.org/junit4/javadoc/latest/org/hamcrest/Matcher.html[`Matcher`]. Instead,
developers are encouraged to use the built-in support for matchers provided by third-party
assertion libraries.

The following example demonstrates how to use the `assertThat()` support from Hamcrest in
a JUnit Jupiter test. As long as the Hamcrest library has been added to the classpath,
you can statically import methods such as `assertThat()`, `is()`, and `equalTo()` and
then use them in tests like in the `assertWithHamcrestMatcher()` method below.

[source,java,indent=0]
----
include::example$java/example/HamcrestAssertionsDemo.java[tags=user_guide]
----

Naturally, legacy tests based on the JUnit 4 programming model can continue using
`org.junit.Assert#assertThat`.
