unit-test-scheduled-async

Q: How do I install unit-test-scheduled-async?

Run npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-scheduled-async in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/unit-test-scheduled-async/ (personal) or .claude/skills/unit-test-scheduled-async/ (project).

by giuseppe-trisciuoglioTesting & QA

Provides patterns for unit testing Spring @Scheduled and @Async methods using JUnit 5, CompletableFuture, Awaitility, and Mockito. Covers mocking task execution and timing, verifying execution counts, testing cron expressions, validating retry behavior, and simulating thread pool behavior. Use when testing background tasks, cron jobs, periodic execution, scheduled tasks, or thread pool behavior.

Installs: 3.7K
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-scheduled-async

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads unit-test-scheduled-async automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

Call @Async methods directly — bypass Spring's async proxy; the annotation is irrelevant in unit tests
Mock dependencies with @Mock and @InjectMocks (Mockito)
Wait for completion — use CompletableFuture.get(timeout, unit) or await().atMost(...).untilAsserted(...)
Call @Scheduled methods directly — do not wait for cron/fixedRate; the annotation is ignored in unit tests
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

FAQ

What does the unit-test-scheduled-async skill do?

How do I install unit-test-scheduled-async?

Run npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-scheduled-async in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/unit-test-scheduled-async/ (personal) or .claude/skills/unit-test-scheduled-async/ (project).

Which AI agents can use unit-test-scheduled-async?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is unit-test-scheduled-async safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains unit-test-scheduled-async?

It is published by giuseppe-trisciuoglio in giuseppe-trisciuoglio/developer-kit. It has 3,739 recorded installs.