Unit Test Scheduled Async

Unit Testing @Scheduled and @Async Methods

Overview

Patterns for unit testing Spring @Scheduled and @Async methods with JUnit 5. Test CompletableFuture results, use Awaitility for race conditions, mock scheduled task execution, and validate error handling — without waiting for real scheduling intervals.

When to Use

• Testing @Scheduled method logic
• Testing @Async method behavior
• Verifying CompletableFuture results
• Testing async error handling
• Testing cron expression logic without waiting for actual scheduling
• Validating thread pool behavior and execution counts
• Testing background task logic in isolation

Instructions

1. Call `@Async` methods directly — bypass Spring's async proxy; the annotation is irrelevant in unit tests 2. Mock dependencies with @Mock and @InjectMocks (Mockito) 3. Wait for completion — use CompletableFuture.get(timeout, unit) or await().atMost(...).untilAsserted(...) 4. Call `@Scheduled` methods directly — do not wait for cron/fixedRate; the annotation is ignored in unit tests 5. Test exception paths — verify ExecutionException wrapping on CompletableFuture.get()

Validation checkpoints:

• After CompletableFuture.get(), assert the returned value before verifying mock interactions
• If ExecutionException is thrown, check .getCause() to identify the root exception
• If Awaitility times out, increase atMost() duration or reduce pollInterval() until the condition is reachable
• After multiple task invocations, assert execution counts before verify() calls

Examples

Key patterns — complete examples in references/examples.md:

// @Async: call directly, wait with 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: call directly, mock the repository
@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: use for race conditions with shared mutable state
@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));
}

// Mocked dependencies with exception handling
@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);
}

Full Maven/Gradle dependencies, additional test classes, and execution count patterns: see references/examples.md.

Best Practices

• Always set a timeout on CompletableFuture.get() to prevent hanging tests
• Mock all dependencies — never call real external services in unit tests
• Use Awaitility only for race conditions; prefer direct calls for simple async methods
• Test @Scheduled logic directly — the annotation is ignored in unit tests
• Assert values before verifying mock interactions; verify after async completion

Common Pitfalls

• Relying on Spring's async executor instead of calling methods directly
• Missing timeout on CompletableFuture.get()
• Forgetting to test exception propagation in async methods
• Not mocking dependencies that async methods invoke internally
• Waiting for actual cron/fixedRate timing instead of testing logic in isolation

Constraints and Warnings

• `@Async` self-invocation: calling @Async from another method in the same class executes synchronously — the Spring proxy is bypassed
• Thread pool ordering: ThreadPoolTaskScheduler does not guarantee execution order
• CompletableFuture chaining: exceptions in intermediate stages can be silently lost — test each stage
• Awaitility timeout: always set a reasonable atMost(); infinite waits hang the test suite
• No actual scheduling: @Scheduled is ignored in unit tests — call methods directly

References

• Spring `@Async` Documentation
• Spring `@Scheduled` Documentation
• Awaitility Testing Library
• CompletableFuture API
• Code examples: references/examples.md

Async & Scheduled Testing — Code Examples

Maven Dependencies

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.awaitility</groupId>
  <artifactId>awaitility</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <scope>test</scope>
</dependency>

Gradle Dependencies

dependencies {
  implementation("org.springframework.boot:spring-boot-starter")
  testImplementation("org.junit.jupiter:junit-jupiter")
  testImplementation("org.awaitility:awaitility")
  testImplementation("org.assertj:assertj-core")
}

Basic Async Testing with CompletableFuture

@Service
public class EmailService {

  @Async
  public CompletableFuture<Boolean> sendEmailAsync(String to, String subject) {
    return CompletableFuture.supplyAsync(() -> {
      System.out.println("Sending email to " + to);
      return true;
    });
  }

  @Async
  public void notifyUser(String userId) {
    System.out.println("Notifying user: " + userId);
  }
}

// Unit test
class EmailServiceAsyncTest {

  @Test
  void shouldReturnCompletedFutureWhenSendingEmail() throws Exception {
    EmailService service = new EmailService();
    CompletableFuture<Boolean> result = service.sendEmailAsync("test@example.com", "Hello");
    Boolean success = result.get(); // Wait for completion
    assertThat(success).isTrue();
  }

  @Test
  void shouldCompleteWithinTimeout() {
    EmailService service = new EmailService();
    CompletableFuture<Boolean> result = service.sendEmailAsync("test@example.com", "Hello");
    assertThat(result).isCompletedWithValue(true);
  }
}

Async Service with Mocked Dependencies

@Service
public class UserNotificationService {
  private final EmailService emailService;
  private final SmsService smsService;

  public UserNotificationService(EmailService emailService, SmsService smsService) {
    this.emailService = emailService;
    this.smsService = smsService;
  }

  @Async
  public CompletableFuture<String> notifyUserAsync(String userId) {
    return CompletableFuture.supplyAsync(() -> {
      emailService.send(userId);
      smsService.send(userId);
      return "Notification sent";
    });
  }
}

@ExtendWith(MockitoExtension.class)
class UserNotificationServiceAsyncTest {

  @Mock
  private EmailService emailService;
  @Mock
  private SmsService smsService;
  @InjectMocks
  private UserNotificationService notificationService;

  @Test
  void shouldNotifyUserAsynchronously() throws Exception {
    CompletableFuture<String> result = notificationService.notifyUserAsync("user123");
    String message = result.get();
    assertThat(message).isEqualTo("Notification sent");
    verify(emailService).send("user123");
    verify(smsService).send("user123");
  }

  @Test
  void shouldHandleAsyncExceptionGracefully() {
    doThrow(new RuntimeException("Email service failed")).when(emailService).send(any());
    CompletableFuture<String> result = notificationService.notifyUserAsync("user123");
    assertThatThrownBy(result::get)
      .isInstanceOf(ExecutionException.class)
      .hasCauseInstanceOf(RuntimeException.class);
  }
}

Testing @Scheduled Methods

@Component
public class DataRefreshTask {
  private final DataRepository dataRepository;

  public DataRefreshTask(DataRepository dataRepository) {
    this.dataRepository = dataRepository;
  }

  @Scheduled(fixedDelay = 60000)
  public void refreshCache() {
    dataRepository.findAll(); // Update cache
  }

  @Scheduled(cron = "0 0 * * * *") // Every hour
  public void cleanupOldData() {
    dataRepository.deleteOldData(LocalDateTime.now().minusDays(30));
  }
}

@ExtendWith(MockitoExtension.class)
class DataRefreshTaskTest {

  @Mock
  private DataRepository dataRepository;
  @InjectMocks
  private DataRefreshTask dataRefreshTask;

  @Test
  void shouldRefreshCacheFromRepository() {
    when(dataRepository.findAll()).thenReturn(List.of(new Data(1L, "item1")));
    dataRefreshTask.refreshCache(); // Call directly — no cron needed
    verify(dataRepository).findAll();
  }

  @Test
  void shouldCleanupOldData() {
    dataRefreshTask.cleanupOldData();
    verify(dataRepository).deleteOldData(any(LocalDateTime.class));
  }
}

Testing Async with Awaitility

@Service
public class BackgroundWorker {
  private final AtomicInteger processedCount = new AtomicInteger(0);

  @Async
  public void processItems(List<String> items) {
    items.forEach(item -> processedCount.incrementAndGet());
  }

  public int getProcessedCount() { return processedCount.get(); }
}

class AwaitilityAsyncTest {

  @Test
  void shouldProcessAllItemsAsynchronously() {
    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 shouldTimeoutWhenProcessingTakesTooLong() {
    BackgroundWorker worker = new BackgroundWorker();
    worker.processItems(List.of("item1"));
    assertThatThrownBy(() ->
      Awaitility.await().atMost(Duration.ofMillis(100)).until(() -> worker.getProcessedCount() == 10)
    ).isInstanceOf(ConditionTimeoutException.class);
  }
}

Testing Scheduled Task Execution Count

@Component
public class HealthCheckTask {
  private final HealthCheckService healthCheckService;
  private int executionCount = 0;

  public HealthCheckTask(HealthCheckService healthCheckService) {
    this.healthCheckService = healthCheckService;
  }

  @Scheduled(fixedRate = 5000)
  public void checkHealth() {
    executionCount++;
    healthCheckService.check();
  }

  public int getExecutionCount() { return executionCount; }
}

class ScheduledTaskTimingTest {

  @Test
  void shouldExecuteTaskMultipleTimes() {
    HealthCheckService mockService = mock(HealthCheckService.class);
    HealthCheckTask task = new HealthCheckTask(mockService);
    task.checkHealth();
    task.checkHealth();
    task.checkHealth();
    assertThat(task.getExecutionCount()).isEqualTo(3);
    verify(mockService, times(3)).check();
  }
}