Unit Testing Spring Caching

Overview

This skill provides patterns for unit testing Spring caching annotations (@Cacheable , @CacheEvict , @CachePut ) without full Spring context. It covers cache hits/misses, invalidation, key generation, and conditional caching using in-memory ConcurrentMapCacheManager .

When to Use

• Writing unit tests for @Cacheable method behavior

• Verifying @CacheEvict cache invalidation works correctly

• Testing @CachePut cache updates

• Validating cache key generation from SpEL expressions

• Testing conditional caching with unless /condition parameters

• Mocking cache managers in fast unit tests without Redis

Instructions

• Configure in-memory CacheManager: Use ConcurrentMapCacheManager for tests

• Set up test fixtures: Mock repository and create service instance in @BeforeEach

• Verify repository call counts: Use times(n) assertions to confirm cache behavior

• Test cache hit: Call method twice, verify repository called once

• Test cache miss: Verify repository called on each invocation

• Test eviction: After @CacheEvict , verify repository called again on next read

• Test key generation: Verify compound keys from SpEL expressions

• Validate conditional caching: Test unless (null results) and condition (parameter-based)

Validation checkpoints:

• Run test → If cache not working: verify @EnableCaching annotation present

• If proxy issues: ensure method calls go through Spring proxy (no direct this calls)

• If key mismatches: log actual cache key and compare with @Cacheable(key="...") expression

Examples

Maven

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-cache</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency>

Gradle

dependencies { implementation("org.springframework.boot:spring-boot-starter-cache") testImplementation("org.springframework.boot:spring-boot-starter-test") }

Testing @Cacheable (Cache Hit/Miss)

// Service @Service public class UserService { private final UserRepository userRepository;

public UserService(UserRepository userRepository) { this.userRepository = userRepository; }

@Cacheable("users") public User getUserById(Long id) { return userRepository.findById(id).orElse(null); } }

// Test class UserServiceCachingTest {

private UserRepository userRepository; private UserService userService;

@BeforeEach void setUp() { userRepository = mock(UserRepository.class); userService = new UserService(userRepository); }

@Test void shouldCacheUserAfterFirstCall() { User user = new User(1L, "Alice"); when(userRepository.findById(1L)).thenReturn(Optional.of(user));

// First call - hits database
User firstCall = userService.getUserById(1L);
// Second call - hits cache
User secondCall = userService.getUserById(1L);

assertThat(firstCall).isEqualTo(secondCall);
verify(userRepository, times(1)).findById(1L); // Only once due to cache

}

@Test void shouldInvokeRepositoryOnCacheMiss() { when(userRepository.findById(1L)).thenReturn(Optional.of(new User(1L, "Bob")));

userService.getUserById(1L);
userService.getUserById(1L);

verify(userRepository, times(2)).findById(1L); // No caching occurred

} }

Testing @CacheEvict

// Service @Service public class ProductService { private final ProductRepository productRepository;

public ProductService(ProductRepository productRepository) { this.productRepository = productRepository; }

@Cacheable("products") public Product getProductById(Long id) { return productRepository.findById(id).orElse(null); }

@CacheEvict("products") public void deleteProduct(Long id) { productRepository.deleteById(id); } }

// Test class ProductCacheEvictTest {

private ProductRepository productRepository; private ProductService productService;

@BeforeEach void setUp() { productRepository = mock(ProductRepository.class); productService = new ProductService(productRepository); }

@Test void shouldEvictProductFromCacheWhenDeleted() { Product product = new Product(1L, "Laptop", 999.99); when(productRepository.findById(1L)).thenReturn(Optional.of(product));

productService.getProductById(1L); // Cache the product
productService.deleteProduct(1L); // Evict from cache

// Repository called again after eviction
productService.getProductById(1L);
verify(productRepository, times(2)).findById(1L);

}

@Test void shouldClearAllEntriesWithAllEntriesTrue() { Product product1 = new Product(1L, "Laptop", 999.99); Product product2 = new Product(2L, "Mouse", 29.99); when(productRepository.findById(anyLong())).thenAnswer(i -> Optional.of(new Product(i.getArgument(0), "Product", 10.0)));

productService.getProductById(1L);
productService.getProductById(2L);

// Use reflection or clear() on ConcurrentMapCache
productService.clearAllProducts();

productService.getProductById(1L);
productService.getProductById(2L);

verify(productRepository, times(4)).findById(anyLong());

} }

Testing @CachePut

@Service public class OrderService { private final OrderRepository orderRepository;

public OrderService(OrderRepository orderRepository) { this.orderRepository = orderRepository; }

@Cacheable("orders") public Order getOrder(Long id) { return orderRepository.findById(id).orElse(null); }

@CachePut(value = "orders", key = "#order.id") public Order updateOrder(Order order) { return orderRepository.save(order); } }

class OrderCachePutTest {

private OrderRepository orderRepository; private OrderService orderService;

@BeforeEach void setUp() { orderRepository = mock(OrderRepository.class); orderService = new OrderService(orderRepository); }

@Test void shouldUpdateCacheWhenOrderIsUpdated() { Order original = new Order(1L, "Pending", 100.0); Order updated = new Order(1L, "Shipped", 100.0);

when(orderRepository.findById(1L)).thenReturn(Optional.of(original));
when(orderRepository.save(updated)).thenReturn(updated);

orderService.getOrder(1L);
orderService.updateOrder(updated);

// Next call returns updated version from cache
Order cachedOrder = orderService.getOrder(1L);
assertThat(cachedOrder.getStatus()).isEqualTo("Shipped");

} }

Testing Conditional Caching

@Service public class DataService { private final DataRepository dataRepository;

public DataService(DataRepository dataRepository) { this.dataRepository = dataRepository; }

// Don't cache null results @Cacheable(value = "data", unless = "#result == null") public Data getData(Long id) { return dataRepository.findById(id).orElse(null); }

// Only cache when id > 0 @Cacheable(value = "users", condition = "#id > 0") public User getUser(Long id) { return dataRepository.findById(id).map(u -> new User(u.getId(), u.getName())).orElse(null); } }

class ConditionalCachingTest {

@Test void shouldNotCacheNullResults() { DataRepository dataRepository = mock(DataRepository.class); when(dataRepository.findById(999L)).thenReturn(Optional.empty()); DataService service = new DataService(dataRepository);

service.getData(999L);
service.getData(999L);

verify(dataRepository, times(2)).findById(999L); // Called twice - no caching

}

@Test void shouldNotCacheWhenConditionIsFalse() { DataRepository dataRepository = mock(DataRepository.class); when(dataRepository.findById(-1L)).thenReturn(Optional.of(new Data(-1L, "Test")));

DataService service = new DataService(dataRepository);

service.getUser(-1L);
service.getUser(-1L);

verify(dataRepository, times(2)).findById(-1L); // Condition "#id > 0" = false

} }

Testing Cache Keys with SpEL

@Service public class InventoryService { private final InventoryRepository inventoryRepository;

public InventoryService(InventoryRepository inventoryRepository) { this.inventoryRepository = inventoryRepository; }

// Compound key: productId-warehouseId @Cacheable(value = "inventory", key = "#productId + '-' + #warehouseId") public InventoryItem getInventory(Long productId, Long warehouseId) { return inventoryRepository.findByProductAndWarehouse(productId, warehouseId); } }

class CacheKeyTest {

@Test void shouldUseCorrectCacheKeyForDifferentCombinations() { InventoryRepository repository = mock(InventoryRepository.class); InventoryItem item = new InventoryItem(1L, 1L, 100); when(repository.findByProductAndWarehouse(1L, 1L)).thenReturn(item);

InventoryService service = new InventoryService(repository);

// Same key: "1-1" - should cache
service.getInventory(1L, 1L);
service.getInventory(1L, 1L); // Cache hit
verify(repository, times(1)).findByProductAndWarehouse(1L, 1L);

// Different key: "2-1" - cache miss
service.getInventory(2L, 1L); // Cache miss
verify(repository, times(2)).findByProductAndWarehouse(any(), any());

} }

Best Practices

• Mock repository calls: Use verify(mock, times(n)) to assert cache behavior

• Test both hit and miss scenarios: Don't just test the happy path

• Clear cache state: Reset between tests to avoid flaky results

• Use ConcurrentMapCacheManager : Fast, no external dependencies

• Verify eviction: Always test that @CacheEvict actually invalidates cached data

Constraints and Warnings

• @Cacheable requires proxy: Direct method calls (this.method() ) bypass caching - use dependency injection

• Cache key collisions: Compound keys from SpEL must be unique per dataset

• Null caching: Null results are cached by default - use unless = "#result == null" to exclude

• @CachePut always executes: Unlike @Cacheable , it always runs the method

• Memory usage: In-memory caches grow unbounded - consider TTL for long-running tests

• Thread safety: ConcurrentMapCacheManager is thread-safe; distributed caches may require additional config

Troubleshooting

Issue Solution

Cache not working Verify @EnableCaching on test config

Proxy bypass Use autowired/constructor injection, not direct this calls

Key mismatch Log cache key with cache.getNativeKey() to debug SpEL

Flaky tests Clear cache in @BeforeEach before each test

References

• Spring Caching Documentation

• Cacheable Annotation

• SpEL Expressions