FakeClock class final

A clock that moves only by elapse, and the zone (run) whose timers and microtasks it owns: a timer started there fires when elapse reaches its time, a microtask runs when the clock flushes them (flushMicrotasks), which elapse does after every timer. Its stopwatch reads it.

Code outside the zone keeps real time. In the zone, only the timers and microtasks are fake: Stopwatch() and DateTime.now() read real time (an app's AppBinding.now() is on stopwatch). A future completed outside the zone resumes the code of the zone that awaits it in a microtask of the real event loop (the SDK keeps some completed in the root zone, as StreamSubscription.cancel returns): flushing lets the real event loop run its microtasks too, until neither queue has any left.

A timer started in the clock's zone fires once the clock reaches it:

final clock = FakeClock();
var fired = false;
clock.run(() => Timer(const Duration(seconds: 1), () => fired = true));
await clock.elapse(const Duration(milliseconds: 999));
expect(fired, isFalse);
await clock.elapse(const Duration(milliseconds: 1));
expect(fired, isTrue);

A periodic timer of no period fires once a microsecond, as one that fired at once would keep the clock where it is: moving the clock on by a second fires it a million times, which a test of such a timer, a loop the app should not have, notices by its time.

A TwkTester runs its app on one (TwkTester.clock); an app run by hand runs on one when its binding reads stopwatch and is started in the zone (elapseUntil has it).

Constructors

FakeClock()
A clock at zero, with no timers, whose zone is a child of the zone it is created in.

Properties

elapsed → Duration
How far the clock has moved since it was created.
no setter
hashCode → int
The hash code for this object.
no setterinherited
nextTimerDue → Duration?
The time on the clock (elapsed) the next timer fires at; null while none waits.
no setter
pendingTimers → int
How many timers wait to fire, periodic ones included.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
stopwatch → Stopwatch
A stopwatch on this clock, running since it was created: until it is stopped or reset it reads elapsed.
latefinal

Methods

describeTimers() → String
The timers that wait, one a line, the next due first: when each is due, its period where it is periodic, and where it was started, the first lines of its stack outside the SDK and this clock; no timer waits while none does. A failure that waited on them says so with it, as elapseUntil's and a tester's pumpUntilIdle's do.
elapse(Duration duration) → Future<void>
Moves the clock on by duration, firing each timer as the clock reaches its time — at or before the end, in the order of their times, those due together in the order they were started — with the microtasks flushed before the first and after each one.
elapseUntil<T>(Future<T> future, {Duration step = const Duration(milliseconds: 10), Duration within = const Duration(seconds: 1)}) → Future<T>
future, once the clock has moved on until it completed, step at a time as elapse moves it: what code run in the clock's zone ends with — an app's run, an answer to a prompt — once the timers it waits on have fired, however long the machine takes to run them. A future that completes without the clock moving is returned with the clock where it was. A TestFailure once the clock has moved on by within and future has not completed, saying how many timers wait.
flushMicrotasks() → Future<void>
Runs the microtasks scheduled in the clock's zone, those they schedule included, in order, and lets the real event loop run its own, until neither has any left.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
run<T>(T body()) → T
Runs body in the clock's zone and returns what it returns; the microtasks it schedules wait for flushMicrotasks.
toString() → String
A string representation of this object.
inherited

Operators

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