giuseppe-trisciuoglio/developer-kit

unit-test-scheduled-async

Provides patterns for unit testing Spring @Scheduled and @Async methods using JUnit 5, CompletableFuture, Awaitility, and Mockito.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-scheduled-async

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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:

java
// @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

관련 작업

같은 저장소의 Skills

더 많은 Skills

모든 Skills
giuseppe-trisciuoglio
커뮤니티

drizzle-orm-patterns

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

1시간 설치 수
3
GitHub Stars
372
업데이트
9월 10일
giuseppe-trisciuoglio
커뮤니티

tailwind-css-patterns

Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.

1시간 설치 수
1
GitHub Stars
372
업데이트
9월 10일
giuseppe-trisciuoglio
커뮤니티

dynamodb-toolbox-patterns

Provides TypeScript patterns for DynamoDB-Toolbox v2 including schema/table/entity modeling, .build() command workflow, query/scan access patterns, batch and transaction operations, and single-table design with computed keys. Use when implementing type-safe DynamoDB access layers with DynamoDB-Toolbox v2 in TypeScript services or serverless applications.

1시간 설치 수
1
GitHub Stars
371
업데이트
9월 10일
giuseppe-trisciuoglio
커뮤니티

spring-boot-dependency-injection

Provides dependency injection patterns for Spring Boot projects, including constructor-first design, optional collaborator handling, bean selection, and wiring validation. Use when creating services and configurations, replacing field injection, or troubleshooting ambiguous or fragile Spring wiring.

1시간 설치 수
1
GitHub Stars
371
업데이트
9월 10일