How to Effectively Unit Test CompletableFuture – 如何有效地对 CompletableFuture 进行单元测试

1. Introduction

1.导言

CompletableFuture is a powerful tool for asynchronous programming in Java. It provides a convenient way to chain asynchronous tasks together and handle their results. It is commonly used in situations where asynchronous operations need to be performed, and their results need to be consumed or processed at a later stage.

CompletableFuture 是 Java 异步编程的强大工具。它提供了一种将异步任务链在一起并处理其结果的便捷方法。它通常用于需要执行异步操作并在稍后阶段消耗或处理其结果的情况。

However, unit testing CompletableFuture can be challenging due to its asynchronous nature. Traditional testing methods, which rely on sequential execution, often fall short of capturing the nuances of asynchronous code. In this tutorial, we’ll discuss how to effectively unit test CompletableFuture using two different approaches: black-box testing and state-based testing.

然而，由于 CompletableFuture 的异步特性，对其进行单元测试可能具有挑战性。传统的测试方法依赖于顺序执行，往往无法捕捉异步代码的细微差别。在本教程中，我们将讨论如何使用两种不同的方法对 CompletableFuture 进行有效的单元测试：黑盒测试和基于状态的测试。

2. Challenges of Testing Asynchronous Code

2.测试异步代码的挑战

Asynchronous code introduces challenges due to its non-blocking and concurrent execution, posing difficulties in traditional testing methods. These challenges include:

由于非阻塞和并发执行，异步代码带来了挑战，给传统测试方法带来了困难。这些挑战包括

• Timing Issues: Asynchronous operations introduce timing dependencies into the code, making it difficult to control the execution flow and verify the behavior of the code at specific points in time. Traditional testing methods that rely on sequential execution may not be suitable for asynchronous code.
• Exception Handling: Asynchronous operations can potentially throw exceptions, and it’s crucial to ensure that the code handles these exceptions gracefully and doesn’t fail silently. Unit tests should cover various scenarios to validate exception handling mechanisms.
• Race Conditions: Asynchronous code can lead to race conditions, where multiple threads or processes attempt to access or modify shared data simultaneously, potentially resulting in unexpected outcomes.
• Test Coverage: Achieving comprehensive test coverage for asynchronous code can be challenging due to the complexity of interactions and the potential for non-deterministic outcomes.

3. Black-Box Testing

3.黑盒测试

Black-box testing focuses on testing the external behavior of the code without knowledge of its internal implementation. This approach is suitable for validating asynchronous code behavior from the user’s perspective. The tester only knows the inputs and expected outputs of the code.

黑盒测试侧重于测试代码的外部行为，而不了解其内部实现。这种方法适用于从用户角度验证异步代码行为。测试人员只知道代码的输入和预期输出。

When testing CompletableFuture using black-box testing, we prioritize the following aspects:

在使用黑盒测试对 CompletableFuture 进行测试时，我们优先考虑以下方面：

• Successful Completion: Verifying that the CompletableFuture completes successfully, returning the anticipated result.
• Exception Handling: Validating that the CompletableFuture handles exceptions gracefully, preventing silent failures.
• Timeouts: Ensuring that the CompletableFuture behaves as expected when encountering timeouts.

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.

我们可以使用类似Mockito的模拟框架来模拟待测CompletableFuture的依赖关系。这将使我们能够隔离 CompletableFuture 并在受控环境中测试其行为。

3.1. System Under Test

3.1 测试中的系统

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.

我们将测试一个名为 processAsync() 的方法，该方法封装了异步数据检索和组合过程。该方法接受一个 Microservice 对象列表作为输入，并返回一个 CompletableFuture<String> 。每个 Microservice 对象代表一个能够执行异步检索操作的微服务。

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

processAsync() 利用两个辅助方法，即 fetchDataAsync() 和 combineResults() 来处理异步数据检索和组合任务：

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>:

fetchDataAsync()方法流过微服务列表，对每个微服务调用retrieveAsync()，并返回一个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:

combineResults() 方法使用 CompletableFuture.allOf() 等待列表中的所有期货完成。完成后，它会映射期货，合并结果，并返回一个字符串：

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

3.2.测试用例：验证数据检索和组合是否成功

This test case verifies that the processAsync() method correctly retrieves data from multiple microservices and combines the results into a single string:

此测试用例验证 processAsync() 方法是否能正确检索多个微服务的数据，并将结果合并为单个字符串：

@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

3.3.测试用例：验证微服务抛出异常时的异常处理

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:

该测试用例验证了 processAsync() 方法是否会在某个微服务抛出异常时抛出 ExecutionException 异常。它还断言异常消息与微服务抛出的异常相同：

@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

3.4.测试用例： 验证当组合结果超过超时时的超时处理

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:

此测试用例尝试在指定的 300 毫秒超时时间内从 processAsync() 方法中检索组合结果。当超过超时时，将抛出 TimeoutException 异常：

@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.

上述代码使用 CompletableFuture.delayedExecutor() 创建执行器，将 retrieveAsync() 调用的完成时间分别延迟 200 和 500 毫秒。这将模拟微服务造成的延迟，并允许测试验证 processAsync() 方法是否正确处理超时。

4. State-Based Testing

4.基于状态的测试

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.

例如，我们可以验证 CompletableFuture 是否会在异步任务成功完成时过渡到完成状态。否则，当出现异常或任务因中断而取消时，它会过渡到失败状态。

4.1. Test Case: Verify State After Successful Completion

4.1.测试用例：验证成功完成后的状态

This test case verifies that a CompletableFuture instance transitions to the done state when all of its constituent CompletableFuture instances have been completed successfully:

此测试用例验证当 CompletableFuture 实例的所有组成 CompletableFuture 实例都已成功完成时，CompletableFuture 实例是否会过渡到完成状态：

@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

4.2.测试用例：验证异常完成后的状态

This test case verifies that when one of the constituent CompletableFuture instances cf2 completes exceptionally, and the allCf CompletableFuture transitions to the exceptional state:

该测试用例验证当组成 CompletableFuture 实例 cf2 中的一个异常完成时，allCf CompletableFuture 是否过渡到异常状态：

@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

4.3.测试用例：验证任务取消后的状态

This test case verifies that when the allCf CompletableFuture is canceled using the cancel(true) method, it transitions to the cancelled state:

此测试用例验证了当使用 cancel(true) 方法取消 allCf CompletableFuture 时，它是否会过渡到已取消状态：

@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

5.结论

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.

总之，由于其异步性质，对 CompletableFuture 进行单元测试可能具有挑战性。然而，这是编写健壮且可维护的异步代码的重要部分。通过使用黑盒测试和基于状态的测试方法，我们可以评估 CompletableFuture 代码在各种条件下的行为，确保其按预期运行，并优雅地处理潜在异常。

As always, the example code is available over on GitHub.

与往常一样，示例代码可在 GitHub 上获取。