在 mockito 中验证异步调用，核心是使用 verify(mock, timeout(1000)) 语法来指定等待结果的最大毫秒数。这要求被测代码必须使用 java 8 的 completablefuture 或类似机制返回异步对象，并在测试中通过 .join() 阻塞主线程直到任务完成或超时。
如何验证 CompletableFuture 的异步执行
要验证异步方法是否被正确调用，需要结合 timeout 参数和 CompletableFuture 的阻塞特性。当被测类的方法返回 CompletableFuture 时，Mockito 的 timeout 会启动一个后台计时器，如果在指定时间内 mock 对象的方法未被调用，测试将失败；如果超过时间但方法仍未被调用，也会抛出异常。关键在于测试代码必须显式调用 .join() 来同步等待异步任务的执行结果，否则主线程可能在异步任务完成前就退出，导致断言失效。
import org.junit.jupiter.api.Test;
import org.mockito.Mockito;
import java.util.concurrent.CompletableFuture;
import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.Mockito.*;
class AsyncService {
public interface DataFetcher {
String fetchData(String key);
}
private final DataFetcher fetcher;
public AsyncService(DataFetcher fetcher) {
this.fetcher = fetcher;
}
public CompletableFuture<String> processAsync(String key) {
return CompletableFuture.supplyAsync(() -> fetcher.fetchData(key));
}
}
public class AsyncTest {
@Test
void testAsyncCallWithTimeout() throws Exception {
// 1. 创建 Mock 对象
AsyncService.DataFetcher mockFetcher = mock(AsyncService.DataFetcher.class);
when(mockFetcher.fetchData("test"))
.thenReturn("result");
// 2. 实例化被测服务
AsyncService service = new AsyncService(mockFetcher);
// 3. 发起异步调用并阻塞等待结果
CompletableFuture<String> future = service.processAsync("test");
String result = future.join(); // 关键：阻塞直到异步完成
// 4. 验证结果
assertEquals("result", result);
// 5. 验证 Mock 在 100ms 内被调用
verify(mockFetcher, timeout(100)).fetchData("test");
}
}
上述代码展示了完整的异步验证流程。首先通过 when(...).thenReturn(...) 设置模拟行为。接着调用 processAsync 获取 CompletableFuture 实例。此时程序不会立即执行内部逻辑，而是继续向下运行。调用 future.join() 是必须的步骤，它会挂起当前测试线程，直到异步任务执行完毕或发生异常。最后使用 verify(mockFetcher, timeout(100)) 确认 fetchData 方法在 100 毫秒内被触发。如果异步任务执行缓慢超过 100 毫秒，或者因为某些原因根本没执行，verify 都会抛出 WantedButNotInvoked 异常。
立即学习“Java免费学习笔记（深入）”；
如何处理异步调用中的异常场景
当异步任务在执行过程中抛出异常时，timeout 验证的行为会有所不同。如果异常发生在 supplyAsync 的 lambda 表达式内部，CompletableFuture 会捕获该异常并将其封装在 Future 中。此时 join() 调用会抛出 CompletionException。在使用 timeout 验证时，即使异步任务抛出了异常，只要该方法在超时时间内被调用了（哪怕只执行了一部分），verify 就会通过。但如果异常导致方法根本没有被调用（例如在提交任务前就出错），则验证会失败。为了准确验证异常路径，通常需要在 when 中配置 thenThrow，并确保 join() 能捕获到预期的异常类型。
import org.junit.jupiter.api.Test;
import org.mockito.Mockito;
import java.util.concurrent.CompletableFuture;
import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.Mockito.*;
public class AsyncExceptionTest {
@Test
void testAsyncCallThrowsException() throws Exception {
// 1. 配置 Mock 抛出异常
AsyncService.DataFetcher mockFetcher = mock(AsyncService.DataFetcher.class);
doThrow(new RuntimeException("Network Error"))
.when(mockFetcher).fetchData("error-key");
AsyncService service = new AsyncService(mockFetcher);
// 2. 发起调用并期望捕获异常
CompletableFuture<String> future = service.processAsync("error-key");
try {
future.join();
fail("Expected CompletionException");
} catch (Exception e) {
// 验证异常类型
assertTrue(e.getCause() instanceof RuntimeException);
assertEquals("Network Error", e.getCause().getMessage());
}
// 3. 验证方法在超时内被调用（即使它抛出了异常）
verify(mockFetcher, timeout(100)).fetchData("error-key");
}
}
这段代码演示了异常情况的处理。通过 doThrow 模拟网络错误。在测试块中，我们尝试调用 join() 并预期它会抛出异常。通过捕获 Exception 并检查其 getCause()，我们可以确认异步任务确实执行了并且抛出了预期的错误。紧接着的 verify(mockFetcher, timeout(100)) 依然有效，因为它只关心方法是否被调用过，而不关心调用后的结果是成功还是失败。这种模式确保了即使在故障场景下，也能验证异步调用的时序约束。
为什么 timeout 验证有时会在快速测试中失败
在使用 timeout 进行单元测试时，偶尔会遇到测试不稳定或随机失败的情况，这通常是因为系统负载或 JVM 启动延迟导致异步任务执行时间超过了设定的阈值。虽然 timeout(100) 表示最多等待 100 毫秒，但如果 CPU 繁忙或 GC 停顿，简单的 supplyAsync 任务也可能耗时较长。为了避免这种不稳定性，建议在测试中适当增加 timeout 的值，或者在本地开发环境中使用更宽松的超时时间。此外，确保 join() 在 verify 之前调用至关重要，因为 verify 只是检查调用记录，而 join() 才是真正驱动异步任务完成的动作。如果先执行 verify 再执行 join()，可能会因为主线程提前结束而导致异步任务未完全执行就被中断，从而引发不可预测的行为。
