0
# Awaitility
1

2
Awaitility is a Java DSL for synchronizing asynchronous operations. It makes it easy to test asynchronous code by providing a clean, readable API that allows developers to express expectations about asynchronous behavior without dealing with low-level threading, timeout, and concurrency concerns.
3

4
## Package Information
5

6
- **Package Name**: awaitility
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.awaitility
10
- **Artifact ID**: awaitility
11
- **Version**: 4.3.0
12

13
### Installation
14

15
**Maven:**
16
```xml
17
<dependency>
18
    <groupId>org.awaitility</groupId>
19
    <artifactId>awaitility</artifactId>
20
    <version>4.3.0</version>
21
    <scope>test</scope>
22
</dependency>
23
```
24

25
**Gradle:**
26
```gradle
27
testImplementation 'org.awaitility:awaitility:4.3.0'
28
```
29

30
**SBT:**
31
```scala
32
libraryDependencies += "org.awaitility" % "awaitility" % "4.3.0" % Test
33
```
34

35
## Core Imports
36

37
```java
38
import static org.awaitility.Awaitility.*;
39
import static java.util.concurrent.TimeUnit.*;
40
import static org.awaitility.Durations.*;
41
```
42

43
Optional additional imports for advanced usage:
44
```java
45
import org.awaitility.core.ConditionFactory;
46
import org.awaitility.pollinterval.PollInterval;
47
import org.awaitility.pollinterval.FibonacciPollInterval;
48
```
49

50
## Basic Usage
51

52
```java
53
import static org.awaitility.Awaitility.*;
54
import static java.util.concurrent.TimeUnit.*;
55

56
// Wait at most 5 seconds until customer status is updated
57
await().atMost(5, SECONDS).until(customerStatusHasUpdated());
58

59
// Wait forever until order count is greater than 3
60
await().forever().until(() -> orderService.orderCount(), greaterThan(3));
61

62
// Wait 300 milliseconds until field value equals expected value
63
await().atMost(300, MILLISECONDS)
64
    .until(fieldIn(orderService).withName("orderCount").andOfType(int.class), equalTo(5));
65

66
// Wait with custom polling interval and initial delay
67
with().pollInterval(ONE_HUNDRED_MILLISECONDS)
68
    .and().with().pollDelay(20, MILLISECONDS)
69
    .await("customer registration")
70
    .until(customerStatus(), equalTo(REGISTERED));
71
```
72

73
## Architecture
74

75
Awaitility is built around several key components:
76

77
- **Main DSL Entry Points**: Static methods in `Awaitility` class for creating await statements
78
- **Condition Factory**: Fluent builder pattern for configuring wait conditions and polling behavior
79
- **Wait Constraints**: Flexible timeout strategies supporting minimum, maximum, and hold duration requirements
80
- **Polling Strategies**: Configurable polling intervals including fixed, Fibonacci, and custom patterns
81
- **Exception Handling**: Selective exception ignoring with predicate and matcher support
82
- **Reflection Utilities**: Field access support for testing private state in objects
83
- **Thread Management**: Configurable executor services and polling thread control
84

85
## Capabilities
86

87
### Core Await Operations
88

89
Primary DSL for creating wait conditions with timeout and polling configuration. Foundation for all asynchronous waiting patterns.
90

91
```java { .api }
92
// Main entry points
93
static ConditionFactory await();
94
static ConditionFactory await(String alias);
95
static ConditionFactory with();
96
static ConditionFactory given();
97
static ConditionFactory waitAtMost(Duration timeout);
98
static ConditionFactory waitAtMost(long value, TimeUnit unit);
99
```
100

101
[Core Await Operations](./core-await.md)
102

103
### Condition Evaluation
104

105
Different ways to specify conditions for waiting, including callable evaluation, predicate matching, assertion-based testing, and atomic variable monitoring.
106

107
```java { .api }
108
// Condition evaluation methods
109
<T> T until(Callable<T> supplier, Matcher<? super T> matcher);
110
<T> T until(Callable<T> supplier, Predicate<? super T> predicate);
111
void until(Callable<Boolean> conditionEvaluator);
112
void untilAsserted(ThrowingRunnable assertion);
113
```
114

115
[Condition Evaluation](./condition-evaluation.md)
116

117
### Timeout and Polling Configuration
118

119
Fine-grained control over wait timing, polling intervals, and execution strategies for optimal performance and test reliability.
120

121
```java { .api }
122
// Timeout configuration
123
ConditionFactory atMost(Duration timeout);
124
ConditionFactory atLeast(Duration timeout);
125
ConditionFactory during(Duration timeout);
126
ConditionFactory between(Duration atLeast, Duration atMost);
127
ConditionFactory forever();
128

129
// Polling configuration  
130
ConditionFactory pollInterval(Duration pollInterval);
131
ConditionFactory pollDelay(Duration pollDelay);
132
ConditionFactory pollInterval(PollInterval pollInterval);
133
```
134

135
[Timeout and Polling](./timeout-polling.md)
136

137
### Exception Handling
138

139
Configurable exception ignoring strategies for handling expected failures during condition evaluation without causing test failures.
140

141
```java { .api }
142
// Exception handling
143
ConditionFactory ignoreException(Class<? extends Throwable> exceptionType);
144
ConditionFactory ignoreExceptions();
145
ConditionFactory ignoreExceptionsMatching(Matcher<? super Throwable> matcher);
146
ConditionFactory ignoreExceptionsMatching(Predicate<? super Throwable> predicate);
147
```
148

149
[Exception Handling](./exception-handling.md)
150

151
### Field and Reflection Support
152

153
Utilities for waiting on private field values and object state changes using reflection, ideal for testing internal component state.
154

155
```java { .api }
156
// Field access
157
static FieldSupplierBuilder fieldIn(Object object);
158
static FieldSupplierBuilder fieldIn(Class<?> clazz);
159

160
interface FieldSupplierBuilder {
161
    FieldSupplierBuilder ofType(Class<?> expectedType);
162
    FieldSupplierBuilder withName(String fieldName);
163
    FieldSupplierBuilder withAnnotation(Class<? extends Annotation> annotation);
164
    <T> Callable<T> call();
165
}
166
```
167

168
[Field and Reflection](./field-reflection.md)
169

170
### Atomic Variable Support
171

172
Specialized support for waiting on atomic variable changes with built-in matchers and type-safe operations.
173

174
```java { .api }
175
// Atomic variable conditions
176
Integer untilAtomic(AtomicInteger atomic, Matcher<? super Integer> matcher);
177
Long untilAtomic(AtomicLong atomic, Matcher<? super Long> matcher);
178
<V> V untilAtomic(AtomicReference<V> atomic, Matcher<? super V> matcher);
179
void untilTrue(AtomicBoolean atomic);
180
void untilFalse(AtomicBoolean atomic);
181
```
182

183
[Atomic Variables](./atomic-variables.md)
184

185
### Advanced Configuration
186

187
Global defaults, fail-fast conditions, custom executors, and logging for complex testing scenarios and performance optimization.
188

189
```java { .api }
190
// Global configuration
191
static void setDefaultTimeout(Duration defaultTimeout);
192
static void setDefaultPollInterval(Duration pollInterval);
193
static void setDefaultPollDelay(Duration pollDelay);
194
static void reset();
195

196
// Fail-fast conditions
197
ConditionFactory failFast(Callable<Boolean> failFastCondition);
198
ConditionFactory failFast(String reason, ThrowingRunnable failFastAssertion);
199
```
200

201
[Advanced Configuration](./advanced-config.md)
202

203
## Common Types
204

205
```java { .api }
206
// Core interfaces
207
@FunctionalInterface
208
interface ThrowingRunnable {
209
    void run() throws Exception;
210
}
211

212
@FunctionalInterface
213
interface ConditionEvaluationListener<T> {
214
    void conditionEvaluated(EvaluatedCondition<T> condition);
215
    default void beforeEvaluation(StartEvaluationEvent<T> startEvaluationEvent) {}
216
    default void onTimeout(TimeoutEvent timeoutEvent) {}
217
    default void exceptionIgnored(IgnoredException ignoredException) {}
218
}
219

220
// Event types for ConditionEvaluationListener
221
class EvaluatedCondition<T> {
222
    public String getDescription();
223
    public Matcher<? super T> getMatcher();
224
    public T getCurrentConditionValue();
225
    public long getElapsedTimeInMS();
226
    public Duration getPollInterval();
227
    public long getRemainingTimeInMS();
228
    public boolean isConditionFulfilled();
229
    public String getAlias();
230
}
231

232
class StartEvaluationEvent<T> {
233
    public String getDescription();
234
    public T getCurrentConditionValue();
235
    public long getElapsedTimeInMS();
236
    public long getRemainingTimeInMS();
237
    public String getAlias();
238
}
239

240
class TimeoutEvent {
241
    public String getDescription();
242
    public long getElapsedTimeInMS();
243
    public String getAlias();
244
}
245

246
class IgnoredException {
247
    public Throwable getException();
248
    public String getDescription();
249
    public long getElapsedTimeInMS();
250
    public String getAlias();
251
}
252

253
// Exception types
254
class ConditionTimeoutException extends RuntimeException {
255
    public ConditionTimeoutException(String message);
256
    public ConditionTimeoutException(String message, Throwable cause);
257
}
258

259
class TerminalFailureException extends RuntimeException {
260
    public TerminalFailureException(String message);
261
    public TerminalFailureException(String message, Throwable cause);
262
}
263

264
class DeadlockException extends Throwable {
265
    public DeadlockException(long[] threads);
266
    public String getMessage();
267
    public ThreadInfo[] getThreadInfos();
268
}
269

270
// Field access exceptions
271
class FieldNotFoundException extends RuntimeException {
272
    public FieldNotFoundException(String message);
273
}
274

275
class TooManyFieldsFoundException extends RuntimeException {
276
    public TooManyFieldsFoundException(String message);
277
}
278

279
// SPI Extension Point
280
class Timeout {
281
    /**
282
     * Message shown in timeout exceptions (can be set globally)
283
     */
284
    public static String timeout_message = null;
285
}
286
```
287

288
## Predefined Constants
289

290
```java { .api }
291
// Duration constants from org.awaitility.Durations
292
static final Duration FOREVER;
293
static final Duration ONE_MILLISECOND;
294
static final Duration ONE_HUNDRED_MILLISECONDS;
295
static final Duration TWO_HUNDRED_MILLISECONDS;
296
static final Duration FIVE_HUNDRED_MILLISECONDS;
297
static final Duration ONE_SECOND;
298
static final Duration TWO_SECONDS;
299
static final Duration FIVE_SECONDS;
300
static final Duration TEN_SECONDS;
301
static final Duration ONE_MINUTE;
302
static final Duration TWO_MINUTES;
303
static final Duration FIVE_MINUTES;
304
static final Duration TEN_MINUTES;
305
```