public class Awaitility extends Object
Wait at most 5 seconds until customer status has been updated:
await().atMost(5, SECONDS).until(customerStatusHasUpdated());Wait forever until the call to
orderService.orderCount()
is
greater than 3.
await().forever().until(() -> orderService.orderCount()), greaterThan(3));Wait 300 milliseconds until field in object
myObject
with name
fieldName
and of type int.class
is equal to 4.
await().atMost(300, MILLISECONDS).until(fieldIn(orderService).withName("fieldName").andOfType(int.class), equalTo(3));Advanced usage: Use a poll interval of 100 milliseconds with an initial delay of 20 milliseconds until customer status is equal to "REGISTERED". This example also uses a named await by specifying an alias ("customer registration"). This makes it easy to find out which await statement that failed if you have multiple awaits in the same test.
with().pollInterval(ONE_HUNDERED_MILLISECONDS).and().with().pollDelay(20, MILLISECONDS).await("customer registration") .until(customerStatus(), equalTo(REGISTERED));You can also specify a default timeout, poll interval and poll delay using:
Awaitility.setDefaultTimeout(..) Awaitility.setDefaultPollInterval(..) Awaitility.setDefaultPollDelay(..)You can also reset to the default values using
reset()
.
In order to use Awaitility effectively it's recommended to statically import
the following methods from the Awaitility framework:
A word on poll interval and poll delay: Awaitility starts to check the specified condition (the one you create using the Awaitility DSL) matches for the first time after a "poll delay" (the initial delay before the polling begins). By default Awaitility uses the same poll delay as poll interval which means that it checks the condition periodically first after the given poll delay, and subsequently with the given poll interval; that is conditions are checked after pollDelay then pollDelay+pollInterval, then pollDelay + 2 pollInterval, and so on.
Note that since Awaitility uses polling to verify that a condition matches it's not intended to use it for precise performance testing.
IMPORTANT: Awaitility does nothing to ensure thread safety or thread synchronization! This is your responsibility! Make sure your code is correctly synchronized or that you are using thread safe data structures such as volatile fields or classes such as AtomicInteger and ConcurrentHashMap.
Constructor and Description |
---|
Awaitility() |
Modifier and Type | Method and Description |
---|---|
static ConditionFactory |
await()
Start building an await statement.
|
static ConditionFactory |
await(String alias)
Start building a named await statement.
|
static ConditionFactory |
catchUncaughtExceptions()
Catching uncaught exceptions in other threads.
|
static void |
catchUncaughtExceptionsByDefault()
Instruct Awaitility to catch uncaught exceptions from other threads by
default.
|
static void |
doNotCatchUncaughtExceptionsByDefault()
Instruct Awaitility not to catch uncaught exceptions from other threads.
|
static ConditionFactory |
dontCatchUncaughtExceptions()
Don't catch uncaught exceptions in other threads.
|
static FieldSupplierBuilder |
fieldIn(Class<?> clazz)
Await until a static field matches something.
|
static FieldSupplierBuilder |
fieldIn(Object object)
Await until an instance field matches something.
|
static ConditionFactory |
given()
Start constructing an await statement given some settings.
|
static void |
ignoreExceptionByDefault(Class<? extends Throwable> exceptionType)
Instruct Awaitility to ignore caught exception of the given type during condition evaluation.
|
static void |
ignoreExceptionsByDefault()
Instruct Awaitility to ignore caught or uncaught exceptions during condition evaluation.
|
static void |
ignoreExceptionsByDefaultMatching(org.hamcrest.Matcher<? super Throwable> matcher)
Instruct Awaitility to ignore caught exceptions matching the supplied
matcher during condition evaluation. |
static void |
ignoreExceptionsByDefaultMatching(Predicate<? super Throwable> predicate)
Instruct Awaitility to ignore caught exceptions matching the given
predicate during condition evaluation. |
static void |
pollExecutorService(ExecutorService executorService)
Specify the executor service whose threads will be used to evaluate the poll condition in Awaitility.
|
static void |
pollInSameThread()
Instructs Awaitility to execute the polling of the condition from the same as the test.
|
static void |
pollThread(Function<Runnable,Thread> threadSupplier)
Specify a thread supplier whose thread will be used to evaluate the poll condition in Awaitility.
|
static void |
reset()
Reset the timeout, poll interval, poll delay, uncaught exception handling
to their default values:
|
static void |
setDefaultConditionEvaluationListener(ConditionEvaluationListener defaultConditionEvaluationListener)
Sets the default condition evaluation listener that all await statements will use.
|
static void |
setDefaultFailFastCondition(Callable<Boolean> defaultFailFastCondition)
If the supplied Callable ever returns false, it indicates our condition will never be true, and if so fail the system immediately.
|
static void |
setDefaultFailFastCondition(String failFastFailureReason,
Callable<Boolean> defaultFailFastCondition)
If the supplied Callable ever returns false, it indicates our condition will never be true, and if so fail the system immediately.
|
static void |
setDefaultPollDelay(Duration pollDelay)
Sets the default poll delay that all await statements will use.
|
static void |
setDefaultPollDelay(long pollDelay,
TimeUnit unit)
Sets the default poll delay all await statements will use.
|
static void |
setDefaultPollInterval(Duration pollInterval)
Sets the default poll interval that all await statements will use.
|
static void |
setDefaultPollInterval(long pollInterval,
TimeUnit unit)
Sets the default poll interval that all await statements will use.
|
static void |
setDefaultPollInterval(PollInterval pollInterval)
Sets the default poll interval that all await statements will use.
|
static void |
setDefaultTimeout(Duration defaultTimeout)
Sets the default timeout that all await statements will use.
|
static void |
setDefaultTimeout(long timeout,
TimeUnit unit)
Sets the default timeout all await statements will use.
|
static ConditionFactory |
waitAtMost(Duration timeout)
An alternative to using
await() if you want to specify a timeout
directly. |
static ConditionFactory |
waitAtMost(long value,
TimeUnit unit)
An alternative to using
await() if you want to specify a timeout
directly. |
static ConditionFactory |
with()
Start constructing an await statement with some settings.
|
public static void catchUncaughtExceptionsByDefault()
true
.public static void doNotCatchUncaughtExceptionsByDefault()
public static void ignoreExceptionsByDefault()
false
. Your test will not fail
upon an exception, unless it times out.public static void ignoreExceptionByDefault(Class<? extends Throwable> exceptionType)
false
. Your test will not fail
upon an exception matching the supplied exception type, unless it times out.public static void ignoreExceptionsByDefaultMatching(Predicate<? super Throwable> predicate)
predicate
during condition evaluation.
Exceptions will be treated as evaluating to false
. Your test will not fail
upon an exception matching the supplied predicate, unless it times out.public static void ignoreExceptionsByDefaultMatching(org.hamcrest.Matcher<? super Throwable> matcher)
matcher
during condition evaluation.
Exceptions will be treated as evaluating to false
. Your test will not fail
upon an exception matching the supplied exception type, unless it times out.public static void pollInSameThread()
public static void pollExecutorService(ExecutorService executorService)
executorService
- The executor service that Awaitility will use when polling condition evaluationspublic static void pollThread(Function<Runnable,Thread> threadSupplier)
threadSupplier
- A supplier of the thread that Awaitility will use when pollingpublic static void reset()
public static ConditionFactory await()
public static ConditionFactory await(String alias)
alias
will be displayed indicating
which await statement that failed.alias
- the alias that will be shown if the await timeouts.public static ConditionFactory catchUncaughtExceptions()
public static ConditionFactory dontCatchUncaughtExceptions()
public static ConditionFactory with()
with().pollInterval(20, MILLISECONDS).await().until(somethingHappens());
public static ConditionFactory given()
given().pollInterval(20, MILLISECONDS).then().await().until(somethingHappens());
public static ConditionFactory waitAtMost(Duration timeout)
await()
if you want to specify a timeout
directly.timeout
- the timeoutpublic static ConditionFactory waitAtMost(long value, TimeUnit unit)
await()
if you want to specify a timeout
directly.value
- the valueunit
- the unitpublic static void setDefaultPollInterval(long pollInterval, TimeUnit unit)
pollInterval
- the poll intervalunit
- the unitpublic static void setDefaultPollDelay(long pollDelay, TimeUnit unit)
pollDelay
- the poll delayunit
- the unitpublic static void setDefaultTimeout(long timeout, TimeUnit unit)
timeout
- the timeoutunit
- the unitpublic static void setDefaultPollInterval(Duration pollInterval)
pollInterval
- the new default poll intervalpublic static void setDefaultPollInterval(PollInterval pollInterval)
pollInterval
- the new default poll intervalpublic static void setDefaultPollDelay(Duration pollDelay)
pollDelay
- the new default poll delaypublic static void setDefaultTimeout(Duration defaultTimeout)
defaultTimeout
- the new default timeoutpublic static void setDefaultConditionEvaluationListener(ConditionEvaluationListener defaultConditionEvaluationListener)
defaultConditionEvaluationListener
- handles condition evaluation each time evaluation of a condition occurs. Works only with Hamcrest matcher-based conditions.public static void setDefaultFailFastCondition(Callable<Boolean> defaultFailFastCondition)
TerminalFailureException
if fail fast condition evaluates to true
. If you want to specify a more descriptive error message
then use setDefaultFailFastCondition(String, Callable)
.defaultFailFastCondition
- The terminal failure conditionsetDefaultFailFastCondition(String, Callable)
public static void setDefaultFailFastCondition(String failFastFailureReason, Callable<Boolean> defaultFailFastCondition)
TerminalFailureException
if fail fast condition evaluates to true
.defaultFailFastCondition
- The terminal failure conditionfailFastFailureReason
- A descriptive reason why the fail fast condition has failed, will be included in the TerminalFailureException
thrown if failFastCondition
evaluates to true
.public static FieldSupplierBuilder fieldIn(Object object)
await().until(fieldIn(service).ofType(int.class).andWithName("fieldName"), greaterThan(2));
Here Awaitility waits until a field with name fieldName
and of the int.class
in object service
is greater than 2.
Note that the field must be thread-safe in order to guarantee correct behavior.
object
- The object that contains the field.public static FieldSupplierBuilder fieldIn(Class<?> clazz)
await().until(fieldIn(Service.class).ofType(int.class).andWithName("fieldName"), greaterThan(2));
Here Awaitility waits until a static field with name fieldName
and of the
int.class
in object service
is greater than 2.
Note that the field must be thread-safe in order to guarantee correct behavior.
clazz
- The class that contains the static field.Copyright © 2010–2021. All rights reserved.