@Scheduled および @Async メソッドのユニットテスト

概要

Spring の @Scheduled および @Async メソッドをJUnit 5でユニットテストするためのパターン集。CompletableFuture の結果をテストし、Awaitility を使用して競合状態に対応し、スケジュール実行をモック化し、エラーハンドリングを検証します。実際のスケジューリング間隔を待つ必要はありません。

使用時期

• @Scheduled メソッドロジックのテスト
• @Async メソッド動作のテスト
• CompletableFuture 結果の検証
• 非同期エラーハンドリングのテスト
• 実際のスケジューリングを待たずにcron式ロジックをテスト
• スレッドプール動作と実行回数の検証
• バックグラウンドタスクロジックの単体テスト

手順

1. @Async メソッドを直接呼び出す — Spring の非同期プロキシをバイパスする; ユニットテストではアノテーションは無視される
2. 依存関係をモック化する — @Mock および @InjectMocks (Mockito) を使用
3. 完了を待つ — CompletableFuture.get(timeout, unit) または await().atMost(...).untilAsserted(...) を使用
4. @Scheduled メソッドを直接呼び出す — cron/fixedRate を待たない; ユニットテストではアノテーションは無視される
5. 例外パスをテストする — CompletableFuture.get() で ExecutionException がラップされていることを確認

検証ポイント:

• CompletableFuture.get() の後、モック相互作用を検証する前に戻り値をアサート
• ExecutionException がスローされた場合、.getCause() で根本例外を確認
• Awaitility がタイムアウトした場合、atMost() の時間を増やすか pollInterval() を短縮して条件に到達するまで調整
• 複数のタスク呼び出し後、verify() 呼び出しの前に実行回数をアサート

例

主なパターン — references/examples.md に完全な例があります:

// @Async: 直接呼び出し、CompletableFuture.get(timeout, unit) で待つ
@Service
class EmailService {
  @Async
  public CompletableFuture<Boolean> sendEmailAsync(String to) {
    return CompletableFuture.supplyAsync(() -> true);
  }
}
@Test
void shouldReturnCompletedFuture() throws Exception {
  EmailService service = new EmailService();
  Boolean result = service.sendEmailAsync("test@example.com").get(5, TimeUnit.SECONDS);
  assertThat(result).isTrue();
}

// @Scheduled: 直接呼び出し、リポジトリをモック化
@Component
class DataRefreshTask {
  @InjectMocks private DataRepository dataRepository;
  @Scheduled(fixedDelay = 60000) public void refreshCache() { /* ... */ }
}
@Test
void shouldRefreshCache() {
  when(dataRepository.findAll()).thenReturn(List.of(new Data(1L, "item1")));
  dataRefreshTask.refreshCache();
  verify(dataRepository).findAll();
}

// Awaitility: 共有可変状態での競合状態に使用
@Test
void shouldProcessAllItems() {
  BackgroundWorker worker = new BackgroundWorker();
  worker.processItems(List.of("item1", "item2", "item3"));
  Awaitility.await()
    .atMost(Duration.ofSeconds(5))
    .pollInterval(Duration.ofMillis(100))
    .untilAsserted(() -> assertThat(worker.getProcessedCount()).isEqualTo(3));
}

// モック化された依存関係と例外ハンドリング
@Test
void shouldHandleAsyncExceptionGracefully() {
  doThrow(new RuntimeException("Email failed")).when(emailService).send(any());
  CompletableFuture<String> result = service.notifyUserAsync("user123");
  assertThatThrownBy(result::get)
    .isInstanceOf(ExecutionException.class)
    .hasCauseInstanceOf(RuntimeException.class);
}

Maven/Gradle の依存関係の詳細、追加テストクラス、実行回数パターン: references/examples.md を参照してください。

ベストプラクティス

• CompletableFuture.get() には常に タイムアウト を設定し、テストのハング防止
• すべての依存関係をモック化 — ユニットテストで実際の外部サービスを呼び出さない
• Awaitility は競合状態に のみ使用; 単純な非同期メソッドは直接呼び出しを推奨
• @Scheduled ロジック を直接テスト — ユニットテストではアノテーションは無視される
• モック相互作用の検証前に値をアサート; 非同期完了 後に 検証

よくある落とし穴

• Spring の非同期エグゼキューターに依存する代わりにメソッドを直接呼び出すべき
• CompletableFuture.get() でタイムアウトを忘れる
• 非同期メソッド内の例外伝播テストを忘れる
• 非同期メソッドが内部で呼び出す依存関係をモック化しない
• 実際のcron/fixedRate タイミングを待つ代わりにロジックを単体テストすべき

制約と警告

• @Async 自己呼び出し: 同じクラス内の別のメソッドから @Async を呼び出すと同期実行される — Spring プロキシはバイパスされる
• スレッドプール順序: ThreadPoolTaskScheduler は実行順序を保証しない
• CompletableFuture チェーン: 中間段階の例外はサイレント喪失の可能性 — 各段階をテスト
• Awaitility タイムアウト: 常に合理的な atMost() を設定; 無限待機はテストスイートをハング
• 実際のスケジューリングなし: @Scheduled はユニットテストで無視される — メソッドを直接呼び出す

参考資料

• Spring @Async ドキュメント
• Spring @Scheduled ドキュメント
• Awaitility テスティングライブラリ
• CompletableFuture API
• コード例: references/examples.md