unit-test-application-events_skill

Overview

This skill provides practical patterns and examples for unit testing Spring ApplicationEvent publishers and @EventListener listeners. It focuses on fast, isolated tests using mocks, ArgumentCaptor, and direct listener invocation so you can validate event-driven workflows without booting the full Spring context. It also covers asynchronous listeners and common pitfalls to avoid.

How this skill works

The skill inspects common testing scenarios and supplies concrete patterns: mock ApplicationEventPublisher to capture published events, invoke listener methods directly to verify side effects, and use ArgumentCaptor to assert event payload integrity. For async listeners it shows strategies for waiting (Thread.sleep or Awaitility) and for multi-listener flows it demonstrates manual sequential invocation and verification.

When to use it

• Validating that services publish the correct ApplicationEvent with expected payloads
• Unit testing @EventListener logic and listener side effects without loading Spring context
• Verifying event propagation across multiple listeners and services
• Testing conditional listeners (condition attribute) and exception handling in listeners
• Testing asynchronous @Async listeners and ensuring processing completes

Best practices

• Mock ApplicationEventPublisher in unit tests and capture published events with ArgumentCaptor
• Test listener logic by instantiating the listener and invoking handler methods directly
• Verify event payloads and any side effects on mocked dependencies rather than framework wiring
• Avoid testing Spring framework behavior — focus on your business logic and event contracts
• For async listeners prefer Awaitility or a short wait in tests; keep listeners idempotent and single-responsibility

Example use cases

• Assert a UserService publishes a UserCreatedEvent with correct User object after save
• Unit test EmailService trigger by invoking UserEventListener.onUserCreated and verifying sendWelcomeEmail was called
• Simulate multiple listeners by invoking each listener sequentially and verifying each mock service received expected calls
• Test conditional listeners by creating events that meet and do not meet the condition and asserting behavior
• Verify an @Async listener processes a user by waiting briefly and verifying the backing SlowService was invoked