super_cache_testing

Test utilities for the super_cache family — FakeCache and ManualClock for writing fast, deterministic unit tests that cover TTL expiration without relying on Future.delayed.

Installation

dev_dependencies:
  super_cache_testing: ^1.0.0

FakeCache

A synchronous, in-memory Cache<K,V> with no eviction policy.

import 'package:super_cache_testing/super_cache_testing.dart';

final cache = FakeCache<String, int>();

cache.put('score', 42);
expect(cache.get('score'), 42);
expect(cache.puts, 1);
expect(cache.gets, 1); // hits + misses

Extras

Member	Description
`puts`	Total `put` / `putAll` calls.
`gets`	Total `get` calls (hits + misses).
`metrics`	Standard `CacheMetrics` snapshot (hits, misses, evictions, …).
`reset()`	Clears all entries and resets all counters. Use between test cases.

ManualClock

An injectable time source. Pass it to FakeCache to control TTL expiration without wall-clock delays.

final clock = ManualClock();
final cache = FakeCache<String, int>(clock: clock);

cache.put('score', 42, ttl: const Duration(minutes: 5));
clock.advance(const Duration(minutes: 6));
expect(cache.get('score'), isNull); // expired

API

ManualClock([DateTime? initial])  // defaults to 2024-01-01T00:00:00Z
void advance(Duration duration)   // move clock forward
void setTime(DateTime time)       // jump to absolute time
DateTime get now                  // current clock value

TTL test example

test('cache entry expires after TTL', () {
  final clock = ManualClock();
  final cache = FakeCache<String, String>(clock: clock);

  cache.put('session', 'abc123', ttl: const Duration(hours: 1));
  expect(cache.get('session'), 'abc123');

  clock.advance(const Duration(hours: 1));
  expect(cache.get('session'), isNull); // expired at boundary
});

Reset between test cases

final cache = FakeCache<String, int>();

setUp(() => cache.reset()); // clears entries + counters

test('first test', () {
  cache.put('k', 1);
  expect(cache.puts, 1);
});

test('second test', () {
  expect(cache.puts, 0); // counter was reset
});