CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-awaitility--awaitility

A Java DSL for synchronizing asynchronous operations

—

Pending
Overview
Eval results
Files

timeout-polling.mddocs/

Timeout and Polling Configuration

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

Capabilities

Timeout Configuration

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

Maximum Wait Time

/**
 * Set maximum time to wait for condition
 * @param timeout maximum wait duration
 * @return ConditionFactory for further configuration
 */
ConditionFactory timeout(Duration timeout);

/**
 * Set maximum time to wait for condition  
 * @param timeout maximum wait duration
 * @return ConditionFactory for further configuration
 */
ConditionFactory atMost(Duration timeout);

/**
 * Set maximum time to wait using value and unit
 * @param timeout timeout value
 * @param unit time unit
 * @return ConditionFactory for further configuration
 */
ConditionFactory atMost(long timeout, TimeUnit unit);

Usage Examples:

// Wait at most 30 seconds
await().atMost(Duration.ofSeconds(30)).until(serviceIsReady());

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

// Using timeout() method
await().timeout(TEN_SECONDS).until(connectionIsEstablished());

Minimum Wait Time

/**
 * Set minimum time to wait before condition can succeed
 * @param timeout minimum wait duration
 * @return ConditionFactory for further configuration
 */
ConditionFactory atLeast(Duration timeout);

/**
 * Set minimum time to wait using value and unit
 * @param timeout minimum wait value
 * @param unit time unit
 * @return ConditionFactory for further configuration
 */
ConditionFactory atLeast(long timeout, TimeUnit unit);

Usage Examples:

// Ensure at least 2 seconds pass before condition can succeed
await().atLeast(2, SECONDS).until(delayedOperationCompletes());

// Combine with maximum timeout
await().atLeast(Duration.ofMillis(500))
    .and().atMost(Duration.ofSeconds(10))
    .until(stabilizationCompletes());

Hold Duration

/**
 * Require condition to remain true for specified duration
 * @param timeout duration condition must hold
 * @return ConditionFactory for further configuration
 */
ConditionFactory during(Duration timeout);

/**
 * Require condition to remain true using value and unit
 * @param timeout hold duration value
 * @param unit time unit
 * @return ConditionFactory for further configuration
 */
ConditionFactory during(long timeout, TimeUnit unit);

Usage Examples:

// Condition must stay true for 3 seconds
await().during(3, SECONDS).until(systemIsStable());

// Ensure service remains healthy for duration
await().atMost(30, SECONDS)
    .during(5, SECONDS)
    .until(serviceHealthCheck());

Combined Timeout Constraints

/**
 * Set both minimum and maximum wait times
 * @param atLeast minimum wait duration
 * @param atMost maximum wait duration
 * @return ConditionFactory for further configuration
 */
ConditionFactory between(Duration atLeast, Duration atMost);

/**
 * Set min/max wait times using values and units
 * @param atLeastDuration minimum wait value
 * @param atLeastTimeUnit minimum wait unit
 * @param atMostDuration maximum wait value
 * @param atMostTimeUnit maximum wait unit
 * @return ConditionFactory for further configuration
 */
ConditionFactory between(long atLeastDuration, TimeUnit atLeastTimeUnit, 
                        long atMostDuration, TimeUnit atMostTimeUnit);

Usage Examples:

// Wait between 1 and 10 seconds
await().between(ONE_SECOND, TEN_SECONDS).until(operationCompletes());

// Using separate units
await().between(500, MILLISECONDS, 30, SECONDS).until(cacheWarmsUp());

Forever Timeout

/**
 * Wait indefinitely until condition is satisfied
 * @return ConditionFactory for further configuration
 */
ConditionFactory forever();

Usage Example:

// Wait indefinitely (use with caution and test timeouts)
await().forever().until(userConfirmsAction());

Polling Configuration

Control how frequently Awaitility checks the condition.

Poll Interval

/**
 * Set fixed polling interval
 * @param pollInterval time between condition evaluations
 * @return ConditionFactory for further configuration  
 */
ConditionFactory pollInterval(Duration pollInterval);

/**
 * Set polling interval using value and unit
 * @param pollInterval interval value
 * @param unit time unit
 * @return ConditionFactory for further configuration
 */
ConditionFactory pollInterval(long pollInterval, TimeUnit unit);

/**
 * Set custom polling interval strategy
 * @param pollInterval polling strategy implementation
 * @return ConditionFactory for further configuration
 */
ConditionFactory pollInterval(PollInterval pollInterval);

Usage Examples:

// Poll every 50 milliseconds
await().pollInterval(50, MILLISECONDS).until(quickOperationCompletes());

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

// Use Fibonacci polling strategy
await().pollInterval(new FibonacciPollInterval(Duration.ofMillis(100)))
    .until(resourceBecomesAvailable());

Poll Delay

/**
 * Set initial delay before first condition check
 * @param delay initial delay duration
 * @return ConditionFactory for further configuration
 */
ConditionFactory pollDelay(Duration delay);

/**
 * Set initial delay using value and unit
 * @param delay delay value
 * @param unit time unit
 * @return ConditionFactory for further configuration
 */
ConditionFactory pollDelay(long delay, TimeUnit unit);

Usage Examples:

// Wait 200ms before first check
await().pollDelay(200, MILLISECONDS).until(immediateOperationCompletes());

// Combine delay with interval
with().pollDelay(ONE_SECOND)
    .and().pollInterval(TWO_HUNDRED_MILLISECONDS)
    .await().until(serviceStarts());

Polling Strategies

Custom polling interval implementations for different scenarios.

Fixed Poll Interval

class FixedPollInterval implements PollInterval {
    /**
     * Create fixed interval polling strategy
     * @param pollInterval fixed time between polls
     */
    public FixedPollInterval(Duration pollInterval);
    
    Duration next(int pollCount, Duration previousDuration);
}

Fibonacci Poll Interval

class FibonacciPollInterval implements PollInterval {
    /**
     * Create default Fibonacci polling strategy starting with 1 millisecond
     */
    public FibonacciPollInterval();
    
    /**
     * Create Fibonacci polling strategy with specified time unit
     * @param unit time unit for Fibonacci sequence
     */
    public FibonacciPollInterval(TimeUnit unit);
    
    /**
     * Create Fibonacci polling strategy with offset and time unit
     * @param offset starting point in Fibonacci sequence
     * @param unit time unit for sequence values
     */
    public FibonacciPollInterval(int offset, TimeUnit unit);
    
    Duration next(int pollCount, Duration previousDuration);
}

Static Factory Methods:

/**
 * Create default Fibonacci polling strategy
 * @return FibonacciPollInterval starting with 1 millisecond
 */
static FibonacciPollInterval fibonacci();

/**
 * Create Fibonacci polling strategy with time unit
 * @param unit time unit for Fibonacci values
 * @return FibonacciPollInterval with specified unit
 */
static FibonacciPollInterval fibonacci(TimeUnit unit);

/**
 * Create Fibonacci polling strategy with offset and time unit
 * @param offset starting position in Fibonacci sequence
 * @param unit time unit for sequence values
 * @return FibonacciPollInterval with offset and unit
 */
static FibonacciPollInterval fibonacci(int offset, TimeUnit unit);

Fluent Configuration Methods:

/**
 * Fluent connector for method chaining
 * @return this instance for chaining
 */
FibonacciPollInterval with();

/**
 * Fluent connector for method chaining
 * @return this instance for chaining
 */
FibonacciPollInterval and();

/**
 * Set time unit for Fibonacci sequence
 * @param unit time unit for sequence values
 * @return this instance for chaining
 */
FibonacciPollInterval unit(TimeUnit unit);

/**
 * Set starting offset in Fibonacci sequence
 * @param offset starting position (0-based)
 * @return this instance for chaining
 */
FibonacciPollInterval offset(int offset);

Iterative Poll Interval

class IterativePollInterval implements PollInterval {
    /**
     * Create iterative polling strategy with duration function
     * @param function transforms previous duration to next duration
     */
    public IterativePollInterval(Function<Duration, Duration> function);
    
    /**
     * Create iterative polling strategy with function and start duration
     * @param function transforms duration for each iteration
     * @param startDuration initial duration for first poll
     */
    public IterativePollInterval(Function<Duration, Duration> function, Duration startDuration);
    
    Duration next(int pollCount, Duration previousDuration);
}

Static Factory Methods:

/**
 * Create iterative polling strategy with duration transformation function
 * @param function transforms previous duration to next duration
 * @return IterativePollInterval with transformation function
 */
static IterativePollInterval iterative(Function<Duration, Duration> function);

/**
 * Create iterative polling strategy with function and start duration
 * @param function transforms duration for each iteration
 * @param startDuration initial duration for first poll
 * @return IterativePollInterval with function and start duration
 */
static IterativePollInterval iterative(Function<Duration, Duration> function, Duration startDuration);

Fluent Configuration Methods:

/**
 * Fluent connector for method chaining
 * @return this instance for chaining
 */
IterativePollInterval with();

/**
 * Set starting duration for iterative polling
 * @param duration initial duration for first poll
 * @return this instance for chaining
 */
IterativePollInterval startDuration(Duration duration);

Custom Poll Interval

interface PollInterval {
    /**
     * Calculate next polling interval
     * @param pollCount number of polls executed so far (1-based)
     * @param previousDuration previous polling interval used
     * @return next polling interval to use
     */
    Duration next(int pollCount, Duration previousDuration);
}

Polling Strategy Examples:

// Exponential backoff polling
PollInterval exponentialBackoff = new PollInterval() {
    @Override
    public Duration next(int pollCount, Duration previousDuration) {
        return Duration.ofMillis(Math.min(5000, 100 * (long) Math.pow(2, pollCount - 1)));
    }
};

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

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

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

// Fibonacci with 1 second cap
await().pollInterval(new FibonacciPollInterval(
    Duration.ofMillis(50), 
    Duration.ofSeconds(1)
)).until(variableSpeedOperation());

Execution Control

Control thread execution and polling behavior.

Thread Management

/**
 * Use provided executor service for condition evaluation
 * @param executorService custom executor for polling
 * @return ConditionFactory for further configuration
 */
ConditionFactory pollExecutorService(ExecutorService executorService);

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

/**
 * Execute condition evaluation in same thread as test
 * Use with test framework timeouts for safety
 * @return ConditionFactory for further configuration
 */
ConditionFactory pollInSameThread();

Thread Management Examples:

// Use custom executor service
ExecutorService customExecutor = Executors.newSingleThreadExecutor();
await().pollExecutorService(customExecutor).until(operationCompletes());

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

// Custom thread with specific name
await().pollThread(runnable -> {
    Thread thread = new Thread(runnable);
    thread.setName("AwaitilityCustomThread");
    thread.setDaemon(true);
    return thread;
}).until(threadSpecificOperation());

Configuration Examples

Complex configurations combining multiple timeout and polling options.

// Comprehensive configuration
with().pollInterval(100, MILLISECONDS)
    .and().pollDelay(50, MILLISECONDS)  
    .and().atMost(30, SECONDS)
    .and().atLeast(1, SECONDS)
    .await("complex operation")
    .until(complexCondition());

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

// Custom executor with timeout constraints
ExecutorService priorityExecutor = Executors.newScheduledThreadPool(2);
await().pollExecutorService(priorityExecutor)
    .between(Duration.ofSeconds(2), Duration.ofMinutes(10))
    .pollInterval(Duration.ofMillis(250))
    .until(priorityTaskCompletes());

Install with Tessl CLI

npx tessl i tessl/maven-org-awaitility--awaitility

docs

advanced-config.md

atomic-variables.md

condition-evaluation.md

core-await.md

exception-handling.md

field-reflection.md

index.md

timeout-polling.md

tile.json