We can use a mocking framework like Mockito to mock the dependencies of the CompletableFuture under test. This will allow us to isolate the CompletableFuture and test its behavior in a controlled environment.

3.1. System Under Test

We will be testing a method named processAsync() that encapsulates the asynchronous data retrieval and combination process. This method accepts a list of Microservice objects as input and returns a CompletableFuture<String> . Each Microservice object represents a microservice capable of performing an asynchronous retrieval operation.

The processAsync() utilizes two helper methods, fetchDataAsync() and combineResults() , to handle the asynchronous data retrieval and combination tasks:

CompletableFuture<String> processAsync(List<Microservice> microservices) {
    List<CompletableFuture<String>> dataFetchFutures = fetchDataAsync(microservices);
    return combineResults(dataFetchFutures);
The fetchDataAsync() method streams through the Microservice list, invoking retrieveAsync() for each, and returns a list of CompletableFuture<String>:
private List<CompletableFuture<String>> fetchDataAsync(List<Microservice> microservices) {
    return microservices.stream()
        .map(client -> client.retrieveAsync(""))
        .collect(Collectors.toList());
The combineResults() method uses CompletableFuture.allOf() to wait for all futures in the list to complete. Once complete, it maps the futures, joins the results, and returns a single string:

private CompletableFuture<String> combineResults(List<CompletableFuture<String>> dataFetchFutures) {
    return CompletableFuture.allOf(dataFetchFutures.toArray(new CompletableFuture[0]))
      .thenApply(v -> dataFetchFutures.stream()
        .map(future -> future.exceptionally(ex -> {
            throw new CompletionException(ex);
          .join())
      .collect(Collectors.joining()));
3.2. Test Case: Verify Successful Data Retrieval and Combination
This test case verifies that the processAsync() method correctly retrieves data from multiple microservices and combines the results into a single string:
@Test
public void givenAsyncTask_whenProcessingAsyncSucceed_thenReturnSuccess() 
  throws ExecutionException, InterruptedException {
    Microservice mockMicroserviceA = mock(Microservice.class);
    Microservice mockMicroserviceB = mock(Microservice.class);
    when(mockMicroserviceA.retrieveAsync(any())).thenReturn(CompletableFuture.completedFuture("Hello"));
    when(mockMicroserviceB.retrieveAsync(any())).thenReturn(CompletableFuture.completedFuture("World"));
    CompletableFuture<String> resultFuture = processAsync(List.of(mockMicroserviceA, mockMicroserviceB));
    String result = resultFuture.get();
    assertEquals("HelloWorld", result);
3.3. Test Case: Verify Exception Handling When Microservice Throws an Exception
This test case verifies that the processAsync() method throws an ExecutionException when one of the microservices throws an exception. It also asserts that the exception message is the same as the exception thrown by the microservice:
@Test
public void givenAsyncTask_whenProcessingAsyncWithException_thenReturnException() 
  throws ExecutionException, InterruptedException {
    Microservice mockMicroserviceA = mock(Microservice.class);
    Microservice mockMicroserviceB = mock(Microservice.class);
    when(mockMicroserviceA.retrieveAsync(any())).thenReturn(CompletableFuture.completedFuture("Hello"));
    when(mockMicroserviceB.retrieveAsync(any()))
      .thenReturn(CompletableFuture.failedFuture(new RuntimeException("Simulated Exception")));
    CompletableFuture<String> resultFuture = processAsync(List.of(mockMicroserviceA, mockMicroserviceB));
    ExecutionException exception = assertThrows(ExecutionException.class, resultFuture::get);
    assertEquals("Simulated Exception", exception.getCause().getMessage());
3.4. Test Case:  Verify Timeout Handling When Combined Result Exceeds Timeout
This test case attempts to retrieve the combined result from the processAsync() method within a specified timeout of 300 milliseconds. It asserts that a TimeoutException is thrown when the timeout is exceeded:
@Test
public void givenAsyncTask_whenProcessingAsyncWithTimeout_thenHandleTimeoutException() 
  throws ExecutionException, InterruptedException {
    Microservice mockMicroserviceA = mock(Microservice.class);
    Microservice mockMicroserviceB = mock(Microservice.class);
    Executor delayedExecutor = CompletableFuture.delayedExecutor(200, TimeUnit.MILLISECONDS);
    when(mockMicroserviceA.retrieveAsync(any()))
      .thenReturn(CompletableFuture.supplyAsync(() -> "Hello", delayedExecutor));
    Executor delayedExecutor2 = CompletableFuture.delayedExecutor(500, TimeUnit.MILLISECONDS);
    when(mockMicroserviceB.retrieveAsync(any()))
      .thenReturn(CompletableFuture.supplyAsync(() -> "World", delayedExecutor2));
    CompletableFuture<String> resultFuture = processAsync(List.of(mockMicroserviceA, mockMicroserviceB));
    assertThrows(TimeoutException.class, () -> resultFuture.get(300, TimeUnit.MILLISECONDS));
The above code uses CompletableFuture.delayedExecutor() to create executors that will delay the completion of the retrieveAsync() calls by 200 and 500 milliseconds, respectively. This simulates the delays caused by the microservices and allows the test to verify that the processAsync() method handles timeouts correctly.
4. State-Based Testing
State-based testing focuses on verifying the state transitions of the code as it executes. This approach is particularly useful for testing asynchronous code, as it allows testers to track the code’s progress through different states and ensure that it transitions correctly.

For example, we can verify that the CompletableFuture transitions to the completed state when the asynchronous task is completed successfully. Otherwise, it transits to a failed state when an exception occurs, or the task is cancelled due to interruption.
4.1. Test Case: Verify State After Successful Completion
This test case verifies that a CompletableFuture instance transitions to the done state when all of its constituent CompletableFuture instances have been completed successfully:
@Test
public void givenCompletableFuture_whenCompleted_thenStateIsDone() {
    Executor delayedExecutor = CompletableFuture.delayedExecutor(200, TimeUnit.MILLISECONDS);
    CompletableFuture<String> cf1 = CompletableFuture.supplyAsync(() -> "Hello", delayedExecutor);
    CompletableFuture<String> cf2 = CompletableFuture.supplyAsync(() -> " World");
    CompletableFuture<String> cf3 = CompletableFuture.supplyAsync(() -> "!");
    CompletableFuture<String>[] cfs = new CompletableFuture[] { cf1, cf2, cf3 };
    CompletableFuture<Void> allCf = CompletableFuture.allOf(cfs);
    assertFalse(allCf.isDone());
    allCf.join();
    String result = Arrays.stream(cfs)
      .map(CompletableFuture::join)
      .collect(Collectors.joining());
    assertFalse(allCf.isCancelled());
    assertTrue(allCf.isDone());
    assertFalse(allCf.isCompletedExceptionally());
4.2. Test Case: Verify State After Completing Exceptionally
This test case verifies that when one of the constituent CompletableFuture instances cf2 completes exceptionally, and the allCf CompletableFuture transitions to the exceptional state:
@Test
public void givenCompletableFuture_whenCompletedWithException_thenStateIsCompletedExceptionally() 
  throws ExecutionException, InterruptedException {
    Executor delayedExecutor = CompletableFuture.delayedExecutor(200, TimeUnit.MILLISECONDS);
    CompletableFuture<String> cf1 = CompletableFuture.supplyAsync(() -> "Hello", delayedExecutor);
    CompletableFuture<String> cf2 = CompletableFuture.failedFuture(new RuntimeException("Simulated Exception"));
    CompletableFuture<String> cf3 = CompletableFuture.supplyAsync(() -> "!");
    CompletableFuture<String>[] cfs = new CompletableFuture[] { cf1, cf2, cf3 };
    CompletableFuture<Void> allCf = CompletableFuture.allOf(cfs);
    assertFalse(allCf.isDone());
    assertFalse(allCf.isCompletedExceptionally());
    assertThrows(CompletionException.class, allCf::join);
    assertTrue(allCf.isCompletedExceptionally());
    assertTrue(allCf.isDone());
    assertFalse(allCf.isCancelled());
4.3. Test Case: Verify State After Task Cancelled
This test case verifies that when the allCf CompletableFuture is canceled using the cancel(true) method, it transitions to the cancelled state:
@Test
public void givenCompletableFuture_whenCancelled_thenStateIsCancelled() 
  throws ExecutionException, InterruptedException {
    Executor delayedExecutor = CompletableFuture.delayedExecutor(200, TimeUnit.MILLISECONDS);
    CompletableFuture<String> cf1 = CompletableFuture.supplyAsync(() -> "Hello", delayedExecutor);
    CompletableFuture<String> cf2 = CompletableFuture.supplyAsync(() -> " World");
    CompletableFuture<String> cf3 = CompletableFuture.supplyAsync(() -> "!");
    CompletableFuture<String>[] cfs = new CompletableFuture[] { cf1, cf2, cf3 };
    CompletableFuture<Void> allCf = CompletableFuture.allOf(cfs);
    assertFalse(allCf.isDone());
    assertFalse(allCf.isCompletedExceptionally());
    allCf.cancel(true);
    assertTrue(allCf.isCancelled());
    assertTrue(allCf.isDone());
5. Conclusion
In conclusion, unit testing CompletableFuture can be challenging due to its asynchronous nature. However, it is an important part of writing robust and maintainable asynchronous code. By using black-box and state-based testing approaches, we can assess the behavior of our CompletableFuture code under various conditions, ensuring that it functions as expected and handles potential exceptions gracefully.
As always, the example code is available over on GitHub.
Partner – Bellsoft – NPI EA (cat = Spring)


Just published a new writeup on how to run a standard Java/Boot
application as a Docker container, using the Liberica JDK on top of
Alpaquita Linux:
Spring Boot Application on Liberica Runtime Container.

Partner – Bellsoft – NPI EA (cat = Spring)


Looking for the ideal Linux distro for running modern Spring
apps in the cloud?
Meet Alpaquita Linux: lightweight, secure, and powerful
enough to handle heavy workloads.
This distro is specifically designed for running Java
apps. It builds upon Alpine and features significant
enhancements to excel in high-density container environments while
meeting enterprise-grade security standards.
Specifically, the container image size is ~30% smaller than
standard options, and it consumes up to 30% less RAM:
Alpaquita Containers now.

Partner – Aegik AB – NPI EA (tag = SQL)


Slow MySQL query performance is all too common. Of course
it is.
The Jet Profiler was built entirely for MySQL, so it's
fine-tuned for it and does advanced everything with relaly minimal
impact and no server changes.
out the Profiler

Partner – Codium – NPI EA (cat = Testing)


Explore the secure, reliable, and high-performance Test
Execution Cloud built for scale. Right in your IDE:
CodiumAI. Meaningful Code Tests for Busy Devs

Basically, write code that works the way you meant it to.
Partner – Machinet – NPI EA (cat = Testing)


AI is all the rage these days, but for very good reason. The
highly practical coding companion, you'll get the power of
AI-assisted coding and automated unit test generation.

Machinet's Unit Test AI Agent utilizes your own project
context to create meaningful unit tests that intelligently aligns
with the behavior of the code.

Simplify Your Coding Journey with Machinet AI:
>> Install Machinet
AI in your IntelliJ
Course – LS – All

Get started with Spring Boot and with core Spring,
through the Learn Spring course:
>> CHECK OUT THE
COURSE
res – REST with Spring (eBook) (everywhere)

Learning to build your API

with Spring?
Download the E-book
Starting to test with Mockito?
Download the Guide
eBook – Video Security – NPI EA (cat=Spring Security)

Security basics for a REST API
access to the video
eBook – Persistence – NPI EA (cat=Persistence)

Download
the E-book