com.jayway.awaitility
Class Awaitility

java.lang.Object
  com.jayway.awaitility.Awaitility

public class Awaitility
extends java.lang.Object

Awaitility is a small Java DSL for synchronizing (waiting for) asynchronous operations. It makes it easy to test asynchronous code. Examples:

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().untilCall(to(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(costumerStatus(), 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:

• com.jayway.awaitility.Awaitlity.*

It may also be useful to import these methods:

• com.jayway.awaitility.Duration.*
• java.util.concurrent.TimeUnit.*
• org.hamcrest.Matchers.*
• org.junit.Assert.*

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: If you change the poll interval the poll delay will also change to match the specified poll interval unless you've specified a poll delay explicitly.

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 Summary

Awaitility()

Method Summary

static ConditionFactory	await() Start building an await statement.
static ConditionFactory	await(java.lang.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(java.lang.Class<?> clazz) Await until a static field matches something.
static FieldSupplierBuilder	fieldIn(java.lang.Object object) Await until an instance field matches something.
static ConditionFactory	given() Start constructing an await statement given some settings.
static void	reset() Reset the timeout, poll interval, poll delay, uncaught exception handling to their default values:
static void	setDefaultPollDelay(Duration pollDelay) Sets the default poll delay that all await statements will use.
static void	setDefaultPollDelay(long pollDelay, java.util.concurrent.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, java.util.concurrent.TimeUnit unit) 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, java.util.concurrent.TimeUnit unit) Sets the default timeout all await statements will use.
static <S> S	to(S object) Await until a specific method invocation returns something.
static ConditionFactory	waitAtMost(Duration timeout) An alternative to using await() if you want to specify a timeout directly.
static ConditionFactory	waitAtMost(long value, java.util.concurrent.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.

Methods inherited from class java.lang.Object

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

Constructor Detail

Awaitility

public Awaitility()

Method Detail

catchUncaughtExceptionsByDefault

public static void catchUncaughtExceptionsByDefault()

Instruct Awaitility to catch uncaught exceptions from other threads by default. This is useful in multi-threaded systems when you want your test to fail regardless of which thread throwing the exception. Default is true.

doNotCatchUncaughtExceptionsByDefault

public static void doNotCatchUncaughtExceptionsByDefault()

Instruct Awaitility not to catch uncaught exceptions from other threads. Your test will not fail if another thread throws an exception.

reset

public static void reset()

Reset the timeout, poll interval, poll delay, uncaught exception handling to their default values:

• timeout - 10 seconds
• poll interval - 100 milliseconds
• poll delay - 100 milliseconds
• Catch all uncaught exceptions - true

.

await

public static ConditionFactory await()

Start building an await statement.

Returns:

the condition factory

await

public static ConditionFactory await(java.lang.String alias)

Start building a named await statement. This is useful is cases when you have several awaits in your test and you need to tell them apart. If a named await timeout's the alias will be displayed indicating which await statement that failed.

Parameters:

alias - the alias that will be shown if the await timeouts.

Returns:

the condition factory

catchUncaughtExceptions

public static ConditionFactory catchUncaughtExceptions()

Catching uncaught exceptions in other threads. This will make the await statement fail even if exceptions occur in other threads. This is the default behavior.

Returns:

the condition factory

dontCatchUncaughtExceptions

public static ConditionFactory dontCatchUncaughtExceptions()

Don't catch uncaught exceptions in other threads. This will not make the await statement fail if exceptions occur in other threads.

Returns:

the condition factory

with

public static ConditionFactory with()

Start constructing an await statement with some settings. E.g.

 with().pollInterval(20, MILLISECONDS).await().until(somethingHappens());
 

Returns:

the condition factory

given

public static ConditionFactory given()

Start constructing an await statement given some settings. E.g.

 given().pollInterval(20, MILLISECONDS).then().await().until(somethingHappens());
 

Returns:

the condition factory

waitAtMost

public static ConditionFactory waitAtMost(Duration timeout)

An alternative to using await() if you want to specify a timeout directly.

Parameters:

timeout - the timeout

Returns:

the condition factory

waitAtMost

public static ConditionFactory waitAtMost(long value,
                                          java.util.concurrent.TimeUnit unit)

An alternative to using await() if you want to specify a timeout directly.

Parameters:

value - the value

unit - the unit

Returns:

the condition factory

setDefaultPollInterval

public static void setDefaultPollInterval(long pollInterval,
                                          java.util.concurrent.TimeUnit unit)

Sets the default poll interval that all await statements will use.

Parameters:

pollInterval - the poll interval

unit - the unit

setDefaultPollDelay

public static void setDefaultPollDelay(long pollDelay,
                                       java.util.concurrent.TimeUnit unit)

Sets the default poll delay all await statements will use.

Parameters:

pollDelay - the poll delay

unit - the unit

setDefaultTimeout

public static void setDefaultTimeout(long timeout,
                                     java.util.concurrent.TimeUnit unit)

Sets the default timeout all await statements will use.

Parameters:

timeout - the timeout

unit - the unit

setDefaultPollInterval

public static void setDefaultPollInterval(Duration pollInterval)

Sets the default poll interval that all await statements will use.

Parameters:

pollInterval - the new default poll interval

setDefaultPollDelay

public static void setDefaultPollDelay(Duration pollDelay)

Sets the default poll delay that all await statements will use.

Parameters:

pollDelay - the new default poll delay

setDefaultTimeout

public static void setDefaultTimeout(Duration defaultTimeout)

Sets the default timeout that all await statements will use.

Parameters:

defaultTimeout - the new default timeout

to

public static <S> S to(S object)

Await until a specific method invocation returns something. E.g.

 await().untilCall(to(service).getCount(), greaterThan(2));
 

Here we tell Awaitility to wait until the service.getCount() method returns a value that is greater than 2.

Type Parameters:

S - The type of the service.

Parameters:

object - the object that contains the method of interest.

Returns:

A proxy of the service

fieldIn

public static FieldSupplierBuilder fieldIn(java.lang.Object object)

Await until an instance field matches something. E.g.

 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.

Parameters:

object - The object that contains the field.

Returns:

A field supplier builder which lets you specify the parameters needed to find the field.

fieldIn

public static FieldSupplierBuilder fieldIn(java.lang.Class<?> clazz)

Await until a static field matches something. E.g.

 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.

Parameters:

clazz - The class that contains the static field.

Returns:

A field supplier builder which lets you specify the parameters needed to find the field.