FakeClock class final

A manually or automatically advanced clock.

Two modes:

Manual — the default. delay returns a future that completes only when advance moves time past it. Use this to test ordering and concurrency: what happens when a timeout fires while a request is in flight.

final clock = FakeClock();
final pending = policy.execute(action, operation: 'test', clock: clock);
await clock.advance(const Duration(seconds: 5));
await pending;

Auto-advancing — every delay completes on the next microtask and time jumps forward by the requested amount. Use this to test schedules: run the operation, then assert on requestedDelays.

final clock = FakeClock(autoAdvance: true);
await policy.execute(failingAction, operation: 'test', clock: clock);
expect(clock.requestedDelays, hasLength(2)); // three attempts, two waits
Implemented types
Available extensions
Annotations
  • @visibleForTesting

Constructors

FakeClock({DateTime? initialTime, bool autoAdvance = false})
Creates a fake clock starting at initialTime.

Properties

autoAdvance → bool
Whether delays complete on their own, advancing time as they do.
final
hashCode → int
The hash code for this object.
no setterinherited
pendingCount → int
Number of delays still waiting to complete.
no setter
requestedDelays → List<Duration>
Every delay that has been requested, in order.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
totalRequestedDelay → Duration
The total of every requested delay.
no setter

Methods

advance(Duration duration) → Future<void>
Moves time forward by duration, completing every delay that comes due.
advanceToNext() → Future<Duration?>
Moves time forward to the next pending delay, completing it.
clearRecordedDelays() → void
Forgets every recorded delay, keeping the current time.
delay(Duration duration) → Future<void>
Completes after duration has elapsed on this clock.
override
measure<T>(Future<T> operation()) → Future<(T, Duration)>

Available on Clock, provided by the ClockOperations extension

Measures how long operation takes on this clock.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
now() → DateTime
The current instant, always in UTC.
override
periodic(Duration interval) → Stream<DateTime>

Available on Clock, provided by the ClockOperations extension

Emits an event every interval until the subscription is cancelled.
resolvePending() → Future<void>
Completes every pending delay immediately, without advancing time.
timeout<T>(Future<T> operation(), {required Duration limit, required String name}) → Future<T>

Available on Clock, provided by the ClockOperations extension

Runs operation, failing with AgenticTimeoutException after limit.
toString() → String
A string representation of this object.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited