unit-test-scheduled-async

Unit-test Spring @Async and @Scheduled methods with CompletableFuture and Awaitility.

Updated Apr 5, 2026

Search Tags:#async #mocking #scheduled #junit-5 #completablefuture #awaitility

Ready to run

npx skills add https://github.com/rizaldiem/digital-invitation-web_V2 --skill unit-test-scheduled-async-rizaldiem

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: unit-test-scheduled-async
Source: https://github.com/rizaldiem/digital-invitation-web_V2/tree/main/.windsurf/skills/unit-test-scheduled-async
Command: npx skills add https://github.com/rizaldiem/digital-invitation-web_V2 --skill unit-test-scheduled-async-rizaldiem

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Unit testing asynchronous and scheduled methods is hard because real executors, timing, and thread scheduling make tests slow, flaky, or nondeterministic. This Skill shows patterns to isolate async logic, mock dependencies, and verify scheduling behavior without relying on actual cron triggers or background executors.

Core Features & Use Cases

Direct invocation of @Async/@Scheduled methods to validate business logic without starting schedulers or thread pools.
CompletableFuture and Awaitility guidance to assert async results with timeouts and avoid hanging tests.
Mocking and verification patterns for dependencies called by background tasks, and examples for testing exception handling and execution counts.
Use Case: Test a cache refresh @Scheduled method by calling it directly and verifying repository interactions, or validate an @Async notification method by awaiting the CompletableFuture result and asserting mock invocations.

Quick Start

Call the @Async or @Scheduled method directly in your unit test, await any returned CompletableFuture with a timeout, and verify mocked dependencies were invoked as expected.

Frequently Asked Questions about unit-test-scheduled-async

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I unit test Spring @Async methods that return CompletableFuture?▼

To unit test Spring @Async methods, call the method directly and assert the returned CompletableFuture using explicit timeouts. Awaitility can also be applied to wait for async results deterministically without relying on actual thread pools or background executors.

Why are my @Scheduled task tests flaky and slow?▼

@Scheduled task tests become flaky and slow when depending on real executors, cron triggers, and thread scheduling. You can isolate the scheduling behavior by invoking the scheduled method directly in your JUnit 5 test and verifying mocked dependencies instead of waiting for actual triggers.

What is the best way to verify dependencies called by background tasks in async tests?▼

The best way to verify dependencies in async tests is using Mockito to mock the called components. After directly invoking the @Async or @Scheduled method and awaiting the CompletableFuture, assert the specific mock invocations to validate execution logic and counts.

Does Awaitility work with JUnit 5 for testing scheduled task execution timing?▼

Awaitility works with JUnit 5 to validate scheduled task execution timing. It provides deterministic waits and explicit timeouts for asynchronous assertions, ensuring your @Scheduled and CompletableFuture tests do not hang while verifying execution outcomes.

Can I test exception handling in asynchronous methods without starting a thread pool?▼

You can test exception handling in asynchronous methods without a thread pool by directly invoking the @Async method in your JUnit 5 test. Awaitility and explicit timeouts capture the async exceptions, while Mockito verifies the mocked dependency interactions triggered by the failure.

How to test a cache refresh @Scheduled method without waiting for the cron trigger?▼

To test a cache refresh @Scheduled method without waiting for the cron trigger, call the method directly in your JUnit 5 unit test. Verify the repository interactions using Mockito to ensure the refresh logic executes correctly without relying on actual schedulers.