simulation library

Deterministic simulation testing for dactor.

Runs an actor system on a seeded scheduler with virtual time, so that a test can be repeated under many message orderings and any failure can be replayed exactly from its seed.

Classes

Delivery
A message a simulated system is about to hand to an actor.
Fault
What a FaultPolicy does with a Delivery.
Simulation
One run of an actor system under a seeded scheduler with virtual time. Created by simulate; the test receives it as its argument.

Functions

checkCommands<S, M, C>({required FutureOr<S> setup(Simulation sim), required M model(), required C generate(Random random, M model), required FutureOr<M> apply(Simulation sim, S subject, M model, C command), int seeds = 100, int commands = 30, int firstSeed = 0, FaultPolicy? faults, int maxSteps = 100000}) → void
A property test over sequences of commands.
explore(FutureOr<void> body(Simulation sim), {int seeds = 100, int firstSeed = 0, FaultPolicy? faults, ActorSystemConfig config()?, int maxSteps = 100000, Duration maxTime = const Duration(hours: 1)}) → void
Runs body under seeds different seeds, starting at firstSeed, and stops at the first one it fails under.
randomFaults({double drop = 0, double delay = 0, double crash = 0, Duration maxDelay = const Duration(milliseconds: 100), bool where(Delivery delivery)?}) → FaultPolicy
A FaultPolicy that drops, delays and crashes at random.
simulate<T>(FutureOr<T> body(Simulation sim), {int seed = 0, FaultPolicy? faults, ActorSystemConfig? config, int maxSteps = 100000, Duration maxTime = const Duration(hours: 1)}) → T
Runs body against a simulated actor system and returns its result.

Typedefs

FaultPolicy = Fault Function(Delivery delivery)
Decides, for each user message about to be delivered, whether something goes wrong with it. System messages (supervision, sys requests) and replies to ask are never offered.

Exceptions / Errors

InjectedFault
The error an actor fails with when a simulation makes it crash.
SimulationDeadlock
Thrown when the test is waiting and nothing is left that could wake it: no actor has a message, and no timer is pending.
SimulationFailure
Thrown by explore and checkCommands: the test failed under seed.
SimulationLimitExceeded
Thrown when a simulation does not end within its step or time limit, usually because actors keep each other busy forever.