0
# Core Await Operations
1

2
Primary DSL entry points for creating await statements and configuring basic wait conditions. These static methods form the foundation of all Awaitility operations.
3

4
## Capabilities
5

6
### Basic Await
7

8
Start building an await statement with default configuration.
9

10
```java { .api }
11
/**
12
 * Start building an await statement with default settings
13
 * @return ConditionFactory for configuring and executing conditions
14
 */
15
static ConditionFactory await();
16
```
17

18
**Usage Example:**
19
```java
20
await().until(customerStatusHasUpdated());
21
```
22

23
### Named Await
24

25
Start building a named await statement for better error messages and debugging.
26

27
```java { .api }
28
/**
29
 * Start building a named await statement for debugging
30
 * @param alias name shown in timeout error messages
31
 * @return ConditionFactory for configuring and executing conditions
32
 */
33
static ConditionFactory await(String alias);
34
```
35

36
**Usage Example:**
37
```java
38
await("customer registration").until(customerStatus(), equalTo(REGISTERED));
39
```
40

41
### Exception Handling Configuration
42

43
Enable or disable automatic catching of uncaught exceptions during condition evaluation.
44

45
```java { .api }
46
/**
47
 * Start building an await statement with uncaught exception catching enabled
48
 * @return ConditionFactory with uncaught exception catching enabled
49
 */
50
static ConditionFactory catchUncaughtExceptions();
51

52
/**
53
 * Start building an await statement with uncaught exception catching disabled
54
 * @return ConditionFactory with uncaught exception catching disabled
55
 */
56
static ConditionFactory dontCatchUncaughtExceptions();
57
```
58

59
**Usage Examples:**
60
```java
61
// Enable uncaught exception catching for this await
62
catchUncaughtExceptions().await().until(riskyOperation());
63

64
// Disable uncaught exception catching for this await
65
dontCatchUncaughtExceptions().await().until(cleanOperation());
66
```
67

68
### Fluent Configuration Starters
69

70
Alternative entry points for fluent configuration before await.
71

72
```java { .api }
73
/**
74
 * Start constructing an await statement with settings
75
 * @return ConditionFactory for configuration and await
76
 */
77
static ConditionFactory with();
78

79
/**
80
 * Alternative to with() for readable fluent chains
81
 * @return ConditionFactory for configuration and await  
82
 */
83
static ConditionFactory given();
84
```
85

86
**Usage Examples:**
87
```java
88
with().pollInterval(20, MILLISECONDS).await().until(somethingHappens());
89

90
given().timeout(30, SECONDS)
91
    .and().pollDelay(100, MILLISECONDS)
92
    .await("data processing")
93
    .until(dataIsProcessed());
94
```
95

96
### Direct Timeout Specification
97

98
Create await statements with explicit timeout without additional configuration.
99

100
```java { .api }
101
/**
102
 * Create await with explicit timeout using Duration
103
 * @param timeout maximum wait time
104
 * @return ConditionFactory with timeout pre-configured
105
 */
106
static ConditionFactory waitAtMost(Duration timeout);
107

108
/**
109
 * Create await with explicit timeout using value and unit
110
 * @param value timeout value
111
 * @param unit time unit for timeout
112
 * @return ConditionFactory with timeout pre-configured
113
 */
114
static ConditionFactory waitAtMost(long value, TimeUnit unit);
115
```
116

117
**Usage Examples:**
118
```java
119
waitAtMost(Duration.ofSeconds(10)).until(serviceIsReady());
120
waitAtMost(5, MINUTES).until(batchJobCompletes());
121
```
122

123
### Exception Handling Variants
124

125
Control uncaught exception handling behavior from the start.
126

127
```java { .api }
128
/**
129
 * Enable catching uncaught exceptions from other threads
130
 * @return ConditionFactory with exception catching enabled
131
 */
132
static ConditionFactory catchUncaughtExceptions();
133

134
/**
135
 * Disable catching uncaught exceptions from other threads
136
 * @return ConditionFactory with exception catching disabled
137
 */
138
static ConditionFactory dontCatchUncaughtExceptions();
139
```
140

141
**Usage Examples:**
142
```java
143
// Fail test if any thread throws uncaught exception
144
catchUncaughtExceptions().await().until(multiThreadedOperationCompletes());
145

146
// Ignore uncaught exceptions from other threads
147
dontCatchUncaughtExceptions().await().until(operationCompletes());
148
```
149

150
### Field Access Helpers
151

152
Create suppliers for field-based conditions using reflection.
153

154
```java { .api }
155
/**
156
 * Create field supplier builder for instance fields
157
 * @param object instance containing the field
158
 * @return FieldSupplierBuilder for field specification
159
 */
160
static FieldSupplierBuilder fieldIn(Object object);
161

162
/**
163
 * Create field supplier builder for static fields
164
 * @param clazz class containing the static field
165
 * @return FieldSupplierBuilder for field specification
166
 */
167
static FieldSupplierBuilder fieldIn(Class<?> clazz);
168
```
169

170
**Usage Examples:**
171
```java
172
// Wait for instance field value
173
await().until(fieldIn(orderService).withName("processedCount"), greaterThan(10));
174

175
// Wait for static field value
176
await().until(fieldIn(DatabasePool.class).withName("activeConnections"), lessThan(5));
177
```
178

179
## Global Configuration Methods
180

181
Static methods for setting default behavior across all await statements.
182

183
### Reset Configuration
184

185
```java { .api }
186
/**
187
 * Reset all default configuration to initial values:
188
 * - timeout: 10 seconds
189
 * - poll interval: 100 milliseconds  
190
 * - poll delay: 100 milliseconds
191
 * - catch uncaught exceptions: true
192
 * - ignore exceptions: false
193
 */
194
static void reset();
195
```
196

197
### Default Timeout Configuration
198

199
```java { .api }
200
/**
201
 * Set default timeout for all await statements
202
 * @param timeout default timeout duration
203
 */
204
static void setDefaultTimeout(Duration timeout);
205

206
/**
207
 * Set default timeout using value and unit
208
 * @param timeout timeout value
209
 * @param unit time unit
210
 */
211
static void setDefaultTimeout(long timeout, TimeUnit unit);
212
```
213

214
### Default Poll Configuration
215

216
```java { .api }
217
/**
218
 * Set default poll interval for all await statements
219
 * @param pollInterval default polling interval
220
 */
221
static void setDefaultPollInterval(Duration pollInterval);
222

223
/**
224
 * Set default poll interval using value and unit
225
 * @param pollInterval interval value
226
 * @param unit time unit
227
 */
228
static void setDefaultPollInterval(long pollInterval, TimeUnit unit);
229

230
/**
231
 * Set default poll interval using PollInterval strategy
232
 * @param pollInterval polling strategy implementation
233
 */
234
static void setDefaultPollInterval(PollInterval pollInterval);
235

236
/**
237
 * Set default poll delay for all await statements
238
 * @param pollDelay initial delay before first poll
239
 */
240
static void setDefaultPollDelay(Duration pollDelay);
241

242
/**
243
 * Set default poll delay using value and unit
244
 * @param pollDelay delay value
245
 * @param unit time unit
246
 */
247
static void setDefaultPollDelay(long pollDelay, TimeUnit unit);
248
```
249

250
### Default Exception Handling Configuration
251

252
```java { .api }
253
/**
254
 * Enable catching uncaught exceptions by default for all await statements
255
 */
256
static void catchUncaughtExceptionsByDefault();
257

258
/**
259
 * Disable catching uncaught exceptions by default for all await statements
260
 */
261
static void doNotCatchUncaughtExceptionsByDefault();
262

263
/**
264
 * Ignore all exceptions by default for all await statements
265
 */
266
static void ignoreExceptionsByDefault();
267

268
/**
269
 * Ignore specific exception type by default for all await statements
270
 * @param exceptionType exception class to ignore
271
 */
272
static void ignoreExceptionByDefault(Class<? extends Throwable> exceptionType);
273

274
/**
275
 * Ignore exceptions matching predicate by default for all await statements
276
 * @param predicate function to test exceptions
277
 */
278
static void ignoreExceptionsByDefaultMatching(Predicate<? super Throwable> predicate);
279

280
/**
281
 * Ignore exceptions matching Hamcrest matcher by default for all await statements
282
 * @param matcher Hamcrest matcher for exceptions
283
 */
284
static void ignoreExceptionsByDefaultMatching(Matcher<? super Throwable> matcher);
285
```
286

287
### Default Listener and Logging Configuration
288

289
```java { .api }
290
/**
291
 * Set default condition evaluation listener for all await statements
292
 * @param defaultConditionEvaluationListener listener for evaluation events
293
 */
294
static void setDefaultConditionEvaluationListener(ConditionEvaluationListener defaultConditionEvaluationListener);
295

296
/**
297
 * Set logging listener for condition evaluation events
298
 * @param loggingListener listener that handles logging
299
 */
300
static void setLoggingListener(ConditionEvaluationListener loggingListener);
301

302
/**
303
 * Enable custom logging for condition evaluation
304
 * @param logPrinter consumer that handles log messages
305
 */
306
static void setLogging(Consumer<String> logPrinter);
307

308
/**
309
 * Enable default logging for condition evaluation to System.out
310
 */
311
static void setDefaultLogging();
312
```
313

314
### Default Fail-Fast Configuration
315

316
```java { .api }
317
/**
318
 * Set default fail-fast condition for all await statements
319
 * @param defaultFailFastCondition condition that triggers immediate failure
320
 */
321
static void setDefaultFailFastCondition(Callable<Boolean> defaultFailFastCondition);
322

323
/**
324
 * Set default fail-fast condition with custom failure reason
325
 * @param failFastFailureReason reason shown when fail-fast triggers
326
 * @param defaultFailFastCondition condition that triggers immediate failure
327
 */
328
static void setDefaultFailFastCondition(String failFastFailureReason, Callable<Boolean> defaultFailFastCondition);
329

330
/**
331
 * Set default fail-fast assertion for all await statements
332
 * @param defaultFailFastAssertion assertion that triggers immediate failure
333
 */
334
static void setDefaultFailFastCondition(ThrowingRunnable defaultFailFastAssertion);
335

336
/**
337
 * Set default fail-fast assertion with custom failure reason
338
 * @param failFastFailureReason reason shown when fail-fast triggers
339
 * @param defaultFailFastAssertion assertion that triggers immediate failure
340
 */
341
static void setDefaultFailFastCondition(String failFastFailureReason, ThrowingRunnable defaultFailFastAssertion);
342
```
343

344
### Thread Control Configuration
345

346
```java { .api }
347
/**
348
 * Configure all await statements to poll in the same thread (synchronous polling)
349
 */
350
static void pollInSameThread();
351

352
/**
353
 * Configure all await statements to use a custom executor service for polling
354
 * @param executorService executor service for condition evaluation
355
 */
356
static void pollExecutorService(ExecutorService executorService);
357

358
/**
359
 * Configure all await statements to use a custom thread supplier for polling
360
 * @param threadSupplier function that creates threads for condition evaluation
361
 */
362
static void pollThread(Function<Runnable, Thread> threadSupplier);
363
```
364

365
**Configuration Examples:**
366
```java
367
// Set global defaults at test class setup
368
@BeforeClass
369
public static void configureAwaitility() {
370
    setDefaultTimeout(30, SECONDS);
371
    setDefaultPollInterval(50, MILLISECONDS);
372
    setDefaultPollDelay(10, MILLISECONDS);
373
}
374

375
@AfterClass  
376
public static void resetAwaitility() {
377
    reset(); // Clean up for other tests
378
}
379
```