Testing Asynchronous Flows with Awaitility: The End of Flaky Tests

We’ve all been there. You write a pristine integration test for your user registration flow. It sends a message to Kafka, consumes it, and creates a wallet entry in PostgreSQL.

It passes on your high-performance MacBook M3. You push to production with confidence.

Boom. The Jenkins build fails. You re-run it. It passes. You whisper “Heisenbug” to yourself and move on. Two days later, it fails again, stalling the entire release train. Your team starts ignoring the red builds, and code quality plummets.

The culprit is almost always `Thread.sleep()`. Hardcoded waits assume your CI server is as fast as your laptop. It isn’t. In 2026, with widespread event-driven microservices, we need a smarter way to assert “eventual consistency.” Enter Awaitility.

The “Thread.sleep” Anti-Pattern explained

Let’s look at the crime scene. This is a typical “Junior Developer” approach to testing an asynchronous Kafka consumer:

// ❌ THE BUGGY WAY
userService.register(user);
// "Let's give Kafka 2 seconds to process"
// CRIME: This assumes network latency fits in 2s.
Thread.sleep(2000); 
// Sometimes this fails if Kafka takes 2.1 seconds!
// Sometimes successful after 0.1s, wasting 1.9s of build time!
assertNotNull(walletRepository.findByUser(user));

Why is this catastrophic for engineering teams?

• It fails randomly: On a busy AWS t3.micro instance during peak load, 2 seconds might not be enough.
• It slows down deployment: If the task finishes in 50ms, you are still waiting 1950ms. Multiply that by 500 integration tests, and you’ve explicitly added 15 minutes of idle time to your build cost.

Phase 1: Getting Started with Awaitility

Awaitility is a DSL (Domain Specific Language) that turns “wait” into a descriptive assertion. It polls your code, asking “Are we there yet?” every few milliseconds.

Dependency Setup

If you are using Spring Boot Starter Test, verify this is included. If not, add it explicitly:

<dependency>
    <groupId>org.awaitility</groupId>
    <artifactId>awaitility</artifactId>
    <scope>test</scope>
</dependency>

Refactoring to Robustness

Let’s rewrite that test properly. Using `untilAsserted` is my preferred method because it lets you use your standard JUnit/AssertJ assertions inside the block.

// ✅ THE SENIOR ARCHITECT WAY
userService.register(user);
await()
    .atMost(Duration.ofSeconds(5)) // Maximum limit
    .pollInterval(Duration.ofMillis(100)) // Check frequency
    .untilAsserted(() -> {
        // This block runs repeatedly until it passes or times out
        Wallet wallet = walletRepository.findByUser(user);
        
        // Use standard assertions!
        assertThat(wallet).isNotNull();
        assertThat(wallet.getBalance()).isEqualTo(100);
    });

Phase 2: Advanced Patterns for Heavy Lifting

Basic polling is easy. But production systems are messy. Here is how I use Awaitility in large-scale microservices handling millions of events.

1. Handling “Not Ready Yet” Exceptions

When testing APIs or databases, calling `findById` too early often throws an `EmptyResultDataAccessException` or `EntityNotFoundException` instead of just returning null. By default, Awaitility crashes the test on the first exception.

The Fix: Use `ignoreExceptions()`.

await()
    .ignoreException(EntityNotFoundException.class) // Keep trying if this happens
    .atMost(10, TimeUnit.SECONDS)
    .until(() -> {
        // If this throws EntityNotFoundException, Awaitility just waits and tries again
        return userStatusService.getStatus(userId).equals("ACTIVE");
    });

2. Testing Kafka & Message Queues

Testing void methods that consume messages is tricky because there is no return value to check. We often use an `AtomicReference` or a concurrent list to capture the side effect.

// Capture the message in a thread-safe container
AtomicReference<String> capturedMessage = new AtomicReference<>();
// Mock the listener to update our container
doAnswer(invocation -> {
    capturedMessage.set(invocation.getArgument(0));
    return null;
}).when(messageListener).onMessage(anyString());
// Trigger the flow
producer.send("Hello World");
// Wait until the container has the expected value
await().untilAtomic(capturedMessage, equalTo("Hello World"));

Phase 3: Debugging the Un-Debuggable

The worst part of async tests is when they fail with: ConditionTimeoutException: Condition not satisfied within 10 seconds.

Great. But why? Was the value null? Was it “PENDING” instead of “COMPLETED”?

I configure Awaitility globally in my `BaseIntegrationTest` to be more verbose. This is a game changer for debugging failures.

@BeforeAll
static void setup() {
    Awaitility.setDefaultPollInterval(100, TimeUnit.MILLISECONDS);
    Awaitility.setDefaultTimeout(5, TimeUnit.SECONDS);
    // CRITICAL: This ensures intermediate exceptions are logged!
    Awaitility.catchUncaughtExceptions(); 
}

Phase 4: Writing Custom Matchers

Sometimes your condition is complex. Instead of writing a massive lambda, write a custom Hamcrest matcher. This makes your tests read like English.

await().until(inventoryService::getStock, hasEnoughItemsFor(order));
// Custom Matcher
private Matcher<Integer> hasEnoughItemsFor(Order order) {
    return new TypeSafeMatcher<Integer>() {
        @Override
        protected boolean matchesSafely(Integer stock) {
            return stock >= order.getQuantity();
        }
        @Override
        public void describeTo(Description description) {
            description.appendText("stock should be greater than " + order.getQuantity());
        }
    };
}

Phase 5: The Kotlin DSL (Bonus)

If you are lucky enough to be using Kotlin in 2026, the syntax gets even improved. Awaitility provides a Kotlin extension module that removes the Java boilerplate.

// Kotlin Syntax - Clean and Readable
await untilCallTo { userService.count() } matches { it == 5 }
// Or with lambda
await until { 
    walletRepository.findAll().any { it.balance > 0 } 
}

Common Pitfalls to Avoid

Frequently Asked Questions

Conclusion

Asynchronous architectures are the standard in 2026, but they brought testing headaches. `Thread.sleep` is a band-aid that eventually falls off, leaving you with a broken build pipeline.

Awaitility tests fixes the root cause: it synchronizes your test state with your system state. If you want a green CI dashboard on Monday morning, refactor your sleeps today.