How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-scheduled-asyncBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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
@Scheduledmethod logic - Testing
@Asyncmethod behavior - Verifying
CompletableFutureresults - 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
- Call `@Async` methods directly — bypass Spring's async proxy; the annotation is irrelevant in unit tests
- Mock dependencies with
@Mockand@InjectMocks(Mockito) - Wait for completion — use
CompletableFuture.get(timeout, unit)orawait().atMost(...).untilAsserted(...) - Call `@Scheduled` methods directly — do not wait for cron/fixedRate; the annotation is ignored in unit tests
- Test exception paths — verify
ExecutionExceptionwrapping onCompletableFuture.get()
Validation checkpoints:
- After
CompletableFuture.get(), assert the returned value before verifying mock interactions - If
ExecutionExceptionis thrown, check.getCause()to identify the root exception - If Awaitility times out, increase
atMost()duration or reducepollInterval()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
@Scheduledlogic 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
@Asyncfrom another method in the same class executes synchronously — the Spring proxy is bypassed - Thread pool ordering:
ThreadPoolTaskSchedulerdoes 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:
@Scheduledis ignored in unit tests — call methods directly
References
- Spring `@Async` Documentation
- Spring `@Scheduled` Documentation
- Awaitility Testing Library
- CompletableFuture API
- Code examples:
references/examples.md


