0
# Timeout and Polling Configuration
1

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

4
## Capabilities
5

6
### Timeout Configuration
7

8
Control how long Awaitility will wait for conditions to be satisfied.
9

10
#### Maximum Wait Time
11

12
```java { .api }
13
/**
14
 * Set maximum time to wait for condition
15
 * @param timeout maximum wait duration
16
 * @return ConditionFactory for further configuration
17
 */
18
ConditionFactory timeout(Duration timeout);
19

20
/**
21
 * Set maximum time to wait for condition  
22
 * @param timeout maximum wait duration
23
 * @return ConditionFactory for further configuration
24
 */
25
ConditionFactory atMost(Duration timeout);
26

27
/**
28
 * Set maximum time to wait using value and unit
29
 * @param timeout timeout value
30
 * @param unit time unit
31
 * @return ConditionFactory for further configuration
32
 */
33
ConditionFactory atMost(long timeout, TimeUnit unit);
34
```
35

36
**Usage Examples:**
37
```java
38
// Wait at most 30 seconds
39
await().atMost(Duration.ofSeconds(30)).until(serviceIsReady());
40

41
// Wait at most 5 minutes using TimeUnit
42
await().atMost(5, MINUTES).until(batchProcessingCompletes());
43

44
// Using timeout() method
45
await().timeout(TEN_SECONDS).until(connectionIsEstablished());
46
```
47

48
#### Minimum Wait Time
49

50
```java { .api }
51
/**
52
 * Set minimum time to wait before condition can succeed
53
 * @param timeout minimum wait duration
54
 * @return ConditionFactory for further configuration
55
 */
56
ConditionFactory atLeast(Duration timeout);
57

58
/**
59
 * Set minimum time to wait using value and unit
60
 * @param timeout minimum wait value
61
 * @param unit time unit
62
 * @return ConditionFactory for further configuration
63
 */
64
ConditionFactory atLeast(long timeout, TimeUnit unit);
65
```
66

67
**Usage Examples:**
68
```java
69
// Ensure at least 2 seconds pass before condition can succeed
70
await().atLeast(2, SECONDS).until(delayedOperationCompletes());
71

72
// Combine with maximum timeout
73
await().atLeast(Duration.ofMillis(500))
74
    .and().atMost(Duration.ofSeconds(10))
75
    .until(stabilizationCompletes());
76
```
77

78
#### Hold Duration
79

80
```java { .api }
81
/**
82
 * Require condition to remain true for specified duration
83
 * @param timeout duration condition must hold
84
 * @return ConditionFactory for further configuration
85
 */
86
ConditionFactory during(Duration timeout);
87

88
/**
89
 * Require condition to remain true using value and unit
90
 * @param timeout hold duration value
91
 * @param unit time unit
92
 * @return ConditionFactory for further configuration
93
 */
94
ConditionFactory during(long timeout, TimeUnit unit);
95
```
96

97
**Usage Examples:**
98
```java
99
// Condition must stay true for 3 seconds
100
await().during(3, SECONDS).until(systemIsStable());
101

102
// Ensure service remains healthy for duration
103
await().atMost(30, SECONDS)
104
    .during(5, SECONDS)
105
    .until(serviceHealthCheck());
106
```
107

108
#### Combined Timeout Constraints
109

110
```java { .api }
111
/**
112
 * Set both minimum and maximum wait times
113
 * @param atLeast minimum wait duration
114
 * @param atMost maximum wait duration
115
 * @return ConditionFactory for further configuration
116
 */
117
ConditionFactory between(Duration atLeast, Duration atMost);
118

119
/**
120
 * Set min/max wait times using values and units
121
 * @param atLeastDuration minimum wait value
122
 * @param atLeastTimeUnit minimum wait unit
123
 * @param atMostDuration maximum wait value
124
 * @param atMostTimeUnit maximum wait unit
125
 * @return ConditionFactory for further configuration
126
 */
127
ConditionFactory between(long atLeastDuration, TimeUnit atLeastTimeUnit, 
128
                        long atMostDuration, TimeUnit atMostTimeUnit);
129
```
130

131
**Usage Examples:**
132
```java
133
// Wait between 1 and 10 seconds
134
await().between(ONE_SECOND, TEN_SECONDS).until(operationCompletes());
135

136
// Using separate units
137
await().between(500, MILLISECONDS, 30, SECONDS).until(cacheWarmsUp());
138
```
139

140
#### Forever Timeout
141

142
```java { .api }
143
/**
144
 * Wait indefinitely until condition is satisfied
145
 * @return ConditionFactory for further configuration
146
 */
147
ConditionFactory forever();
148
```
149

150
**Usage Example:**
151
```java
152
// Wait indefinitely (use with caution and test timeouts)
153
await().forever().until(userConfirmsAction());
154
```
155

156
### Polling Configuration
157

158
Control how frequently Awaitility checks the condition.
159

160
#### Poll Interval
161

162
```java { .api }
163
/**
164
 * Set fixed polling interval
165
 * @param pollInterval time between condition evaluations
166
 * @return ConditionFactory for further configuration  
167
 */
168
ConditionFactory pollInterval(Duration pollInterval);
169

170
/**
171
 * Set polling interval using value and unit
172
 * @param pollInterval interval value
173
 * @param unit time unit
174
 * @return ConditionFactory for further configuration
175
 */
176
ConditionFactory pollInterval(long pollInterval, TimeUnit unit);
177

178
/**
179
 * Set custom polling interval strategy
180
 * @param pollInterval polling strategy implementation
181
 * @return ConditionFactory for further configuration
182
 */
183
ConditionFactory pollInterval(PollInterval pollInterval);
184
```
185

186
**Usage Examples:**
187
```java
188
// Poll every 50 milliseconds
189
await().pollInterval(50, MILLISECONDS).until(quickOperationCompletes());
190

191
// Poll every 2 seconds for slow operations
192
await().pollInterval(Duration.ofSeconds(2)).until(slowBatchJobCompletes());
193

194
// Use Fibonacci polling strategy
195
await().pollInterval(new FibonacciPollInterval(Duration.ofMillis(100)))
196
    .until(resourceBecomesAvailable());
197
```
198

199
#### Poll Delay
200

201
```java { .api }
202
/**
203
 * Set initial delay before first condition check
204
 * @param delay initial delay duration
205
 * @return ConditionFactory for further configuration
206
 */
207
ConditionFactory pollDelay(Duration delay);
208

209
/**
210
 * Set initial delay using value and unit
211
 * @param delay delay value
212
 * @param unit time unit
213
 * @return ConditionFactory for further configuration
214
 */
215
ConditionFactory pollDelay(long delay, TimeUnit unit);
216
```
217

218
**Usage Examples:**
219
```java
220
// Wait 200ms before first check
221
await().pollDelay(200, MILLISECONDS).until(immediateOperationCompletes());
222

223
// Combine delay with interval
224
with().pollDelay(ONE_SECOND)
225
    .and().pollInterval(TWO_HUNDRED_MILLISECONDS)
226
    .await().until(serviceStarts());
227
```
228

229
### Polling Strategies
230

231
Custom polling interval implementations for different scenarios.
232

233
#### Fixed Poll Interval
234

235
```java { .api }
236
class FixedPollInterval implements PollInterval {
237
    /**
238
     * Create fixed interval polling strategy
239
     * @param pollInterval fixed time between polls
240
     */
241
    public FixedPollInterval(Duration pollInterval);
242
    
243
    Duration next(int pollCount, Duration previousDuration);
244
}
245
```
246

247
#### Fibonacci Poll Interval
248

249
```java { .api }
250
class FibonacciPollInterval implements PollInterval {
251
    /**
252
     * Create default Fibonacci polling strategy starting with 1 millisecond
253
     */
254
    public FibonacciPollInterval();
255
    
256
    /**
257
     * Create Fibonacci polling strategy with specified time unit
258
     * @param unit time unit for Fibonacci sequence
259
     */
260
    public FibonacciPollInterval(TimeUnit unit);
261
    
262
    /**
263
     * Create Fibonacci polling strategy with offset and time unit
264
     * @param offset starting point in Fibonacci sequence
265
     * @param unit time unit for sequence values
266
     */
267
    public FibonacciPollInterval(int offset, TimeUnit unit);
268
    
269
    Duration next(int pollCount, Duration previousDuration);
270
}
271
```
272

273
**Static Factory Methods:**
274
```java { .api }
275
/**
276
 * Create default Fibonacci polling strategy
277
 * @return FibonacciPollInterval starting with 1 millisecond
278
 */
279
static FibonacciPollInterval fibonacci();
280

281
/**
282
 * Create Fibonacci polling strategy with time unit
283
 * @param unit time unit for Fibonacci values
284
 * @return FibonacciPollInterval with specified unit
285
 */
286
static FibonacciPollInterval fibonacci(TimeUnit unit);
287

288
/**
289
 * Create Fibonacci polling strategy with offset and time unit
290
 * @param offset starting position in Fibonacci sequence
291
 * @param unit time unit for sequence values
292
 * @return FibonacciPollInterval with offset and unit
293
 */
294
static FibonacciPollInterval fibonacci(int offset, TimeUnit unit);
295
```
296

297
**Fluent Configuration Methods:**
298
```java { .api }
299
/**
300
 * Fluent connector for method chaining
301
 * @return this instance for chaining
302
 */
303
FibonacciPollInterval with();
304

305
/**
306
 * Fluent connector for method chaining
307
 * @return this instance for chaining
308
 */
309
FibonacciPollInterval and();
310

311
/**
312
 * Set time unit for Fibonacci sequence
313
 * @param unit time unit for sequence values
314
 * @return this instance for chaining
315
 */
316
FibonacciPollInterval unit(TimeUnit unit);
317

318
/**
319
 * Set starting offset in Fibonacci sequence
320
 * @param offset starting position (0-based)
321
 * @return this instance for chaining
322
 */
323
FibonacciPollInterval offset(int offset);
324
```
325

326
#### Iterative Poll Interval
327

328
```java { .api }
329
class IterativePollInterval implements PollInterval {
330
    /**
331
     * Create iterative polling strategy with duration function
332
     * @param function transforms previous duration to next duration
333
     */
334
    public IterativePollInterval(Function<Duration, Duration> function);
335
    
336
    /**
337
     * Create iterative polling strategy with function and start duration
338
     * @param function transforms duration for each iteration
339
     * @param startDuration initial duration for first poll
340
     */
341
    public IterativePollInterval(Function<Duration, Duration> function, Duration startDuration);
342
    
343
    Duration next(int pollCount, Duration previousDuration);
344
}
345
```
346

347
**Static Factory Methods:**
348
```java { .api }
349
/**
350
 * Create iterative polling strategy with duration transformation function
351
 * @param function transforms previous duration to next duration
352
 * @return IterativePollInterval with transformation function
353
 */
354
static IterativePollInterval iterative(Function<Duration, Duration> function);
355

356
/**
357
 * Create iterative polling strategy with function and start duration
358
 * @param function transforms duration for each iteration
359
 * @param startDuration initial duration for first poll
360
 * @return IterativePollInterval with function and start duration
361
 */
362
static IterativePollInterval iterative(Function<Duration, Duration> function, Duration startDuration);
363
```
364

365
**Fluent Configuration Methods:**
366
```java { .api }
367
/**
368
 * Fluent connector for method chaining
369
 * @return this instance for chaining
370
 */
371
IterativePollInterval with();
372

373
/**
374
 * Set starting duration for iterative polling
375
 * @param duration initial duration for first poll
376
 * @return this instance for chaining
377
 */
378
IterativePollInterval startDuration(Duration duration);
379
```
380

381
#### Custom Poll Interval
382

383
```java { .api }
384
interface PollInterval {
385
    /**
386
     * Calculate next polling interval
387
     * @param pollCount number of polls executed so far (1-based)
388
     * @param previousDuration previous polling interval used
389
     * @return next polling interval to use
390
     */
391
    Duration next(int pollCount, Duration previousDuration);
392
}
393
```
394

395
**Polling Strategy Examples:**
396
```java
397
// Exponential backoff polling
398
PollInterval exponentialBackoff = new PollInterval() {
399
    @Override
400
    public Duration next(int pollCount, Duration previousDuration) {
401
        return Duration.ofMillis(Math.min(5000, 100 * (long) Math.pow(2, pollCount - 1)));
402
    }
403
};
404

405
await().pollInterval(exponentialBackoff).until(retryableOperationSucceeds());
406

407
// Linear increase polling
408
PollInterval linearIncrease = (pollCount, previousDuration) -> 
409
    Duration.ofMillis(100 + (pollCount - 1) * 100);
410

411
await().pollInterval(linearIncrease).until(progressivelySlowerOperation());
412

413
// Fibonacci with 1 second cap
414
await().pollInterval(new FibonacciPollInterval(
415
    Duration.ofMillis(50), 
416
    Duration.ofSeconds(1)
417
)).until(variableSpeedOperation());
418
```
419

420
### Execution Control
421

422
Control thread execution and polling behavior.
423

424
#### Thread Management
425

426
```java { .api }
427
/**
428
 * Use provided executor service for condition evaluation
429
 * @param executorService custom executor for polling
430
 * @return ConditionFactory for further configuration
431
 */
432
ConditionFactory pollExecutorService(ExecutorService executorService);
433

434
/**
435
 * Use custom thread supplier for condition evaluation
436
 * @param threadSupplier function that creates threads for polling
437
 * @return ConditionFactory for further configuration
438
 */
439
ConditionFactory pollThread(Function<Runnable, Thread> threadSupplier);
440

441
/**
442
 * Execute condition evaluation in same thread as test
443
 * Use with test framework timeouts for safety
444
 * @return ConditionFactory for further configuration
445
 */
446
ConditionFactory pollInSameThread();
447
```
448

449
**Thread Management Examples:**
450
```java
451
// Use custom executor service
452
ExecutorService customExecutor = Executors.newSingleThreadExecutor();
453
await().pollExecutorService(customExecutor).until(operationCompletes());
454

455
// Use same thread (with JUnit timeout for safety)
456
@Test(timeout = 5000)
457
public void testWithSameThread() {
458
    await().pollInSameThread().until(immediateCondition());
459
}
460

461
// Custom thread with specific name
462
await().pollThread(runnable -> {
463
    Thread thread = new Thread(runnable);
464
    thread.setName("AwaitilityCustomThread");
465
    thread.setDaemon(true);
466
    return thread;
467
}).until(threadSpecificOperation());
468
```
469

470
### Configuration Examples
471

472
Complex configurations combining multiple timeout and polling options.
473

474
```java
475
// Comprehensive configuration
476
with().pollInterval(100, MILLISECONDS)
477
    .and().pollDelay(50, MILLISECONDS)  
478
    .and().atMost(30, SECONDS)
479
    .and().atLeast(1, SECONDS)
480
    .await("complex operation")
481
    .until(complexCondition());
482

483
// Fibonacci polling with constraints
484
await().pollInterval(new FibonacciPollInterval(
485
        Duration.ofMillis(10),    // Start with 10ms
486
        Duration.ofSeconds(2)))   // Cap at 2 seconds
487
    .atMost(Duration.ofMinutes(5))
488
    .during(Duration.ofMillis(500))  // Must hold for 500ms
489
    .until(stabilizingSystemIsReady());
490

491
// Custom executor with timeout constraints
492
ExecutorService priorityExecutor = Executors.newScheduledThreadPool(2);
493
await().pollExecutorService(priorityExecutor)
494
    .between(Duration.ofSeconds(2), Duration.ofMinutes(10))
495
    .pollInterval(Duration.ofMillis(250))
496
    .until(priorityTaskCompletes());
497
```