This code contains some helper functions for testing xstate v5+ Actor and Machine behavior using Promises and "traditional" assertions (vs state-machine-based testing).
Maybe I'll put some examples here.
Instead of this, see xstate-audition which I built upon this idea (with less OOP).
| /** | |
| * Utilities for testing `xstate` (v5) actors in Node.js | |
| * | |
| * @license Apache-2.0 https://apache.org/licenses/LICENSE-2.0 | |
| * @author <[email protected]> | |
| */ | |
| import {scheduler} from 'node:timers/promises'; | |
| import * as xs from 'xstate'; | |
| /** | |
| * Any event or emitted-event from an actor | |
| */ | |
| export type ActorEvent<T extends xs.AnyActorLogic> = | |
| | xs.EventFromLogic<T> | |
| | xs.EmittedFrom<T>; | |
| /** | |
| * A tuple of events emitted by an actor, based on a {@link ActorEventTypeTuple} | |
| * | |
| * @see {@link AnyActorRunner.runUntilEvent} | |
| */ | |
| export type ActorEventTuple< | |
| T extends xs.AnyActorLogic, | |
| EventTypes extends ActorEventTypeTuple<T>, | |
| > = {[K in keyof EventTypes]: EventFromEventType<T, EventTypes[K]>}; | |
| /** | |
| * The `type` prop of any event or emitted event from an actor | |
| */ | |
| export type ActorEventType<T extends xs.AnyActorLogic> = ActorEvent<T>['type']; | |
| /** | |
| * A tuple of event types (event names) emitted by an actor | |
| * | |
| * @see {@link AnyActorRunner.runUntilEvent} | |
| */ | |
| export type ActorEventTypeTuple<T extends xs.AnyActorLogic> = [ | |
| ActorEventType<T>, | |
| ...ActorEventType<T>, | |
| ]; | |
| /** | |
| * Options for methods in {@link AnyActorRunner} | |
| */ | |
| export type ActorRunnerOptions = { | |
| /** | |
| * Default actor ID to use | |
| */ | |
| id?: string; | |
| /** | |
| * Default inspector to use | |
| * | |
| * @param An {@link xs.InspectionEvent InspectionEvent} | |
| */ | |
| inspect?: (evt: xs.InspectionEvent) => void; | |
| /** | |
| * Default logger to use | |
| * | |
| * @param Anything To be logged | |
| */ | |
| logger?: (...args: any[]) => void; | |
| /** | |
| * Default timeout for those methods which accept a timeout. | |
| */ | |
| timeout?: number; | |
| }; | |
| /** | |
| * Options in {@link ActorRunner} methods where an existing {@link Actor} is | |
| * provided instead of input for a new `Actor`. | |
| * | |
| * These methods cannot and should not overwrite an existing actor's ID. | |
| */ | |
| export type ActorRunnerOptionsWithActor = Omit<ActorRunnerOptions, 'id'>; | |
| /** | |
| * Frankenpromise that is both a `Promise` and an {@link xs.Actor}. | |
| * | |
| * Returned by some methods in {@link AnyActorRunner} | |
| */ | |
| export type ActorThenable< | |
| T extends xs.AnyActorLogic, | |
| Out = void, | |
| > = Promise<Out> & xs.Actor<T>; | |
| /** | |
| * Lookup for event/emitted-event based on type | |
| */ | |
| export type EventFromEventType< | |
| T extends xs.AnyActorLogic, | |
| K extends ActorEventType<T>, | |
| > = xs.ExtractEvent<ActorEvent<T>, K>; | |
| /** | |
| * Options for methods in {@link AnyActorRunner} which provide their own | |
| * inspection callbacks, and thus do allow custom inspectors. | |
| */ | |
| export type OptionsWithoutInspect<T extends ActorRunnerOptions> = Omit< | |
| T, | |
| 'inspect' | |
| >; | |
| export interface ActorRunner<T extends xs.AnyActorLogic> { | |
| /** | |
| * Default actor logic to use | |
| */ | |
| defaultActorLogic: T; | |
| /** | |
| * Default actor ID to use when creating an actor. | |
| */ | |
| defaultId?: string; | |
| /** | |
| * Default inspector to use. | |
| */ | |
| defaultInspector: (evt: xs.InspectionEvent) => void; | |
| /** | |
| * Default logger | |
| */ | |
| defaultLogger: (...args: any[]) => void; | |
| /** | |
| * Default timeout for those methods which accept a timeout. | |
| */ | |
| defaultTimeout: number; | |
| /** | |
| * Runs an actor to completion (or timeout) and fulfills with its output. | |
| * | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param options Options | |
| * @returns `Promise` fulfilling with the actor output | |
| */ | |
| runUntilDone( | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| ): ActorThenable<T, xs.OutputFrom<T>>; | |
| /** | |
| * Runs an actor (or starts a new one) until it emits or sends one or more | |
| * events (in order). | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * Immediately stops the actor thereafter. | |
| * | |
| * @param events One or more _event names_ (the `type` field) to wait for (in | |
| * order) | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param options Options | |
| * @returns An {@link ActorThenable} which fulfills with the matching events | |
| * (assuming they all occurred in order) | |
| */ | |
| runUntilEvent<const EventTypes extends ActorEventTypeTuple<T>>( | |
| events: EventTypes, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| ): ActorThenable<T, ActorEventTuple<T, EventTypes>>; | |
| /** | |
| * Runs an actor until the snapshot predicate returns `true`. | |
| * | |
| * Immediately stops the actor thereafter. | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * @param predicate Snapshot predicate; see {@link xs.waitFor} | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param options Options | |
| * @returns {@link ActorThenable} Fulfilling with the snapshot that matches | |
| * the predicate | |
| */ | |
| runUntilSnapshot( | |
| predicate: (snapshot: xs.SnapshotFrom<T>) => boolean, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| ): ActorThenable<T, xs.SnapshotFrom<T>>; | |
| /** | |
| * Starts an actor, applying defaults, and returns the {@link xs.Actor} object. | |
| * | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param options Options | |
| * @returns The {@link xs.Actor} itself | |
| */ | |
| start(input: xs.InputFrom<T> | xs.Actor<T>): xs.Actor<T>; | |
| /** | |
| * Waits for an actor to be spawned. | |
| * | |
| * "Actor" here refers to _some other actor_--not the actor provided via | |
| * `input` nor created from the input object. | |
| * | |
| * Does **not** stop the root actor. | |
| * | |
| * @param actorId A string or RegExp to match against the actor ID | |
| * @param input Actor input or an {@link xs.Actor} | |
| * @param options Options | |
| * @returns The `ActorRef` of the spawned actor | |
| */ | |
| waitForActor<SpawnedActor extends xs.AnyActorLogic = xs.AnyActorLogic>( | |
| actorId: string | RegExp, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| ): ActorThenable<T, xs.ActorRefFrom<SpawnedActor>>; | |
| /** | |
| * Runs a new or existing actor until the snapshot predicate returns `true`. | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * @param predicate Snapshot predicate; see {@link xs.waitFor} | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param options Options | |
| * @returns {@link ActorThenable} Fulfilling with the snapshot that matches | |
| * the predicate | |
| */ | |
| waitForSnapshot( | |
| predicate: (snapshot: xs.SnapshotFrom<T>) => boolean, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| ): ActorThenable<T, xs.SnapshotFrom<T>>; | |
| } | |
| /** | |
| * An {@link ActorRunner} which provides additional methods for testing state | |
| * machines | |
| */ | |
| export interface StateMachineActorRunner<T extends xs.AnyStateMachine> | |
| extends ActorRunner<T> { | |
| /** | |
| * Runs the machine until a transition from the `source` state to the `target` | |
| * state occurs. | |
| * | |
| * Immediately stops the machine thereafter. Returns a combination of a | |
| * `Promise` and an {@link xs.Actor} so that events may be sent to the actor. | |
| * | |
| * @param source Source state ID | |
| * @param target Target state ID | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param opts Options | |
| * @returns An {@link ActorThenable} that resolves when the specified | |
| * transition occurs | |
| * @todo Type narrowing for `source` and `target` once xstate supports it | |
| */ | |
| runUntilTransition( | |
| source: string, | |
| target: string, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options?: OptionsWithoutInspect< | |
| ActorRunnerOptions | ActorRunnerOptionsWithActor | |
| >, | |
| ): ActorThenable<T>; | |
| /** | |
| * Runs the machine until a transition from the `source` state to the `target` | |
| * state occurs. | |
| * | |
| * Useful for chaining transitions--but keep in mind that actions are executed | |
| * synchronously! | |
| * | |
| * **Does not stop the machine**. Returns a combination of a `Promise` and an | |
| * {@link xs.Actor} so that events may be sent to the actor. | |
| * | |
| * @param source Source state ID | |
| * @param target Target state ID | |
| * @param input Machine input | |
| * @param opts Options | |
| * @returns An {@link ActorThenable} that resolves when the specified | |
| * transition occurs | |
| * @todo Type narrowing for `source` and `target` once xstate supports it | |
| */ | |
| waitForTransition( | |
| source: string, | |
| target: string, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options?: OptionsWithoutInspect< | |
| ActorRunnerOptions | ActorRunnerOptionsWithActor | |
| >, | |
| ): ActorThenable<T>; | |
| } | |
| /** | |
| * An implementation of an {@link ActorRunner} which can help test any actor | |
| * logic. | |
| */ | |
| export class AnyActorRunner<T extends xs.AnyActorLogic> | |
| implements ActorRunner<T> | |
| { | |
| /** | |
| * Used to generate unique actor IDs when no ID is otherwise provided. | |
| * | |
| * Incremented when {@link getActorId} cannot otherwise find an ID. | |
| * | |
| * @internal | |
| */ | |
| public static anonymousActorIndex = 0; | |
| /** | |
| * Default actor logic to use | |
| */ | |
| public defaultActorLogic: T; | |
| /** | |
| * Default actor ID to use when creating an actor. | |
| */ | |
| public defaultId?: string; | |
| /** | |
| * Default inspector to use. | |
| */ | |
| public defaultInspector: (evt: xs.InspectionEvent) => void; | |
| /** | |
| * Default logger | |
| */ | |
| public defaultLogger: (...args: any[]) => void; | |
| /** | |
| * Default timeout for those methods which accept a timeout. | |
| */ | |
| public defaultTimeout: number; | |
| /** | |
| * If `actorLogic` is a state machine, it will use the machine's default ID | |
| * (if present) as {@link AnyActorRunner.defaultId} _unless_ | |
| * {@link ActorRunnerOptions.id} is provided in `options`. | |
| * | |
| * @param actorLogic Any actor logic | |
| * @param options Options | |
| */ | |
| constructor( | |
| actorLogic: T, | |
| { | |
| id: defaultId, | |
| logger: defaultLogger = noop, | |
| inspect: defaultInspector = noop, | |
| timeout: defaultTimeout = DEFAULT_TIMEOUT, | |
| }: ActorRunnerOptions = {}, | |
| ) { | |
| this.defaultActorLogic = actorLogic; | |
| this.defaultLogger = defaultLogger; | |
| this.defaultInspector = defaultInspector; | |
| this.defaultTimeout = defaultTimeout; | |
| this.defaultId = defaultId; | |
| // State machines _may_ have a default ID | |
| if (!this.defaultId && actorLogic instanceof xs.StateMachine) { | |
| this.defaultId = actorLogic.id; | |
| } | |
| } | |
| /** | |
| * Factory function for creating a {@link AnyActorRunner}. | |
| * | |
| * @param actorLogic Any actor logic | |
| * @param options Options | |
| * @returns A new instance of {@link AnyActorRunner} | |
| */ | |
| public static create<T extends xs.AnyActorLogic>( | |
| actorLogic: T, | |
| options?: ActorRunnerOptions, | |
| ): AnyActorRunner<T> { | |
| return new AnyActorRunner(actorLogic, options); | |
| } | |
| /** | |
| * Creates an {@link ActorThenable} from an {@link Actor} and a {@link Promise}. | |
| * | |
| * @param actor An `Actor` | |
| * @param promise Any `Promise` | |
| * @returns An `Actor` which is also a thenable | |
| * @internal | |
| */ | |
| public static createActorThenable<T extends xs.AnyActorLogic, Out = void>( | |
| actor: xs.Actor<T>, | |
| promise: Promise<Out>, | |
| ): ActorThenable<T, Out> { | |
| // there are myriad ways to do this, and here is one. | |
| const pThen = promise.then.bind(promise); | |
| const pCatch = promise.catch.bind(promise); | |
| const pFinally = promise.finally.bind(promise); | |
| return new Proxy(actor, { | |
| get: (target, prop, receiver) => { | |
| switch (prop) { | |
| case 'then': | |
| return pThen; | |
| case 'catch': | |
| return pCatch; | |
| case 'finally': | |
| return pFinally; | |
| default: | |
| return Reflect.get(target, prop, receiver); | |
| } | |
| }, | |
| }) as ActorThenable<T, Out>; | |
| } | |
| /** | |
| * Creates a new `Actor` from the actor logic and the provided input. Assigns | |
| * default or provided `id`, logger and inspector. | |
| * | |
| * @param input Input for actor logic | |
| * @param options Options for {@link xs.createActor}, mostly | |
| * @returns New actor (not started) | |
| * @internal | |
| */ | |
| public createInstrumentedActor( | |
| input: xs.InputFrom<T>, | |
| options: ActorRunnerOptions, | |
| ): xs.Actor<T> { | |
| const { | |
| logger = this.defaultLogger, | |
| inspect = this.defaultInspector, | |
| id = this.defaultId, | |
| } = options; | |
| return xs.createActor(this.defaultActorLogic, { | |
| id, | |
| input, | |
| logger, | |
| inspect, | |
| }); | |
| } | |
| /** | |
| * Gets an actor ID for a new actor or from an existing actor. | |
| * | |
| * If one is otherwise unavailable, a unique ID will be generated matching | |
| * `^__ActorHelpers-\d+__$`. | |
| * | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param id ID, if any | |
| * @returns A unique ID | |
| * @internal | |
| */ | |
| public getActorId<T extends xs.AnyActorLogic>( | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| id = this.defaultId, | |
| ): string { | |
| return input instanceof xs.Actor | |
| ? input.id | |
| : id ?? `__ActorHelpers-${AnyActorRunner.anonymousActorIndex++}__`; | |
| } | |
| /** | |
| * Sets up an existing `Actor` with a logger and inspector. | |
| * | |
| * @param actor Actor | |
| * @param options Options for instrumentation | |
| * @returns Instrumented actor | |
| * @internal | |
| */ | |
| public instrumentActor( | |
| actor: xs.Actor<T>, | |
| options: ActorRunnerOptionsWithActor, | |
| ): xs.Actor<T> { | |
| const {logger = this.defaultLogger, inspect = this.defaultInspector} = | |
| options; | |
| if (inspect !== this.defaultInspector) { | |
| actor.system.inspect(xs.toObserver(inspect)); | |
| } | |
| if (logger !== this.defaultLogger) { | |
| // @ts-expect-error private | |
| // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access | |
| actor.logger = actor._actorScope.logger = logger; | |
| } | |
| return actor; | |
| } | |
| /** | |
| * Runs an actor to completion (or timeout) and fulfills with its output. | |
| * | |
| * @param input Actor input | |
| * @param options Options | |
| * @returns `Promise` fulfilling with the actor output | |
| */ | |
| public runUntilDone( | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options?: ActorRunnerOptions, | |
| ): ActorThenable<T, xs.OutputFrom<T>>; | |
| /** | |
| * Runs an actor to completion (or timeout) and fulfills with its output. | |
| * | |
| * @param actor Actor | |
| * @param options Options | |
| * @returns `Promise` fulfilling with the actor output | |
| */ | |
| public runUntilDone( | |
| actor: xs.Actor<T>, | |
| options?: ActorRunnerOptionsWithActor, | |
| ): ActorThenable<T, xs.OutputFrom<T>>; | |
| /** | |
| * Runs an actor to completion (or timeout) and fulfills with its output. | |
| * | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param options Options | |
| * @returns `Promise` fulfilling with the actor output | |
| */ | |
| @bind() | |
| public runUntilDone( | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options: ActorRunnerOptions | ActorRunnerOptionsWithActor = {}, | |
| ): ActorThenable<T, xs.OutputFrom<T>> { | |
| const {timeout = this.defaultTimeout} = options; | |
| const actor = | |
| input instanceof xs.Actor | |
| ? this.instrumentActor(input, options as ActorRunnerOptionsWithActor) | |
| : this.createInstrumentedActor(input, options as ActorRunnerOptions); | |
| // order is important: create promise, then start. | |
| const p = xs.toPromise(actor); | |
| actor.start(); | |
| const ac = new AbortController(); | |
| return AnyActorRunner.createActorThenable( | |
| actor, | |
| Promise.race([ | |
| p.finally(() => { | |
| ac.abort(); | |
| }), | |
| scheduler.wait(timeout, {signal: ac.signal}).then(() => { | |
| throw new Error(`Actor did not complete in ${timeout}ms`); | |
| }), | |
| ]), | |
| ); | |
| } | |
| /** | |
| * Runs an actor until it emits or sends one or more events (in order). | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * Immediately stops the actor thereafter. | |
| * | |
| * @param events One or more _event names_ (the `type` field) to wait for (in | |
| * order) | |
| * @param input Actor input | |
| * @param options Options | |
| * @returns An {@link ActorThenable} which fulfills with the matching events | |
| * (assuming they all occurred in order) | |
| */ | |
| public runUntilEvent<const EventTypes extends ActorEventTypeTuple<T>>( | |
| events: EventTypes, | |
| input: xs.InputFrom<T>, | |
| options?: OptionsWithoutInspect<ActorRunnerOptions>, | |
| ): ActorThenable<T, ActorEventTuple<T, EventTypes>>; | |
| /** | |
| * Runs an actor until it emits or sends one or more events (in order). | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * Immediately stops the actor thereafter. | |
| * | |
| * @param events One or more _event names_ (the `type` field) to wait for (in | |
| * order) | |
| * @param actor Actor | |
| * @param options Options | |
| * @returns An {@link ActorThenable} which fulfills with the matching events | |
| * (assuming they all occurred in order) | |
| * @todo See if we cannot distinguish between emitted events, sent events, | |
| * etc., at runtime. This would prevent the need to blindly subscribe and | |
| * use the inspector at the same time. | |
| */ | |
| public runUntilEvent<const EventTypes extends ActorEventTypeTuple<T>>( | |
| events: EventTypes, | |
| actor: xs.Actor<T>, | |
| options?: OptionsWithoutInspect<ActorRunnerOptionsWithActor>, | |
| ): ActorThenable<T, ActorEventTuple<T, EventTypes>>; | |
| /** | |
| * Runs an actor (or starts a new one) until it emits or sends one or more | |
| * events (in order). | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * Immediately stops the actor thereafter. | |
| * | |
| * @param events One or more _event names_ (the `type` field) to wait for (in | |
| * order) | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param options Options | |
| * @returns An {@link ActorThenable} which fulfills with the matching events | |
| * (assuming they all occurred in order) | |
| */ | |
| @bind() | |
| public runUntilEvent<const EventTypes extends ActorEventTypeTuple<T>>( | |
| events: EventTypes, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options: OptionsWithoutInspect< | |
| ActorRunnerOptions | ActorRunnerOptionsWithActor | |
| > = {}, | |
| ): ActorThenable<T, ActorEventTuple<T, EventTypes>> { | |
| const expectedEventQueue = [...events]; | |
| if (!expectedEventQueue.length) { | |
| throw new TypeError('Expected one or more event types'); | |
| } | |
| const id = this.getActorId( | |
| input, | |
| (options as OptionsWithoutInspect<ActorRunnerOptions>).id, | |
| ); | |
| // inspector fields events sent to another actor | |
| const runUntilEventInspector = (evt: xs.InspectionEvent) => { | |
| const type = expectedEventQueue[0]; | |
| if (evt.type === '@xstate.event' && type === evt.event.type) { | |
| if (evt.sourceRef?.id === id) { | |
| emitted.push(evt.event as EventFromEventType<T, typeof type>); | |
| expectedEventQueue.shift(); | |
| if (!expectedEventQueue.length) { | |
| evt.sourceRef.stop(); | |
| } | |
| subscription?.unsubscribe(); | |
| } | |
| } | |
| }; | |
| const actor = | |
| input instanceof xs.Actor | |
| ? this.instrumentActor(input, { | |
| ...options, | |
| inspect: runUntilEventInspector, | |
| } as ActorRunnerOptionsWithActor) | |
| : this.createInstrumentedActor(input, { | |
| ...options, | |
| inspect: runUntilEventInspector, | |
| } as ActorRunnerOptions); | |
| const emitted: ActorEventTuple<T, EventTypes> = [] as any; | |
| const {timeout = this.defaultTimeout} = options; | |
| let subscription: xs.Subscription | undefined; | |
| // subscription fields emitted events | |
| const subscribe = (type: EventTypes[number]) => { | |
| subscription = actor.on(type, (evt) => { | |
| subscription?.unsubscribe(); | |
| emitted.push(evt.event as EventFromEventType<T, typeof type>); | |
| expectedEventQueue.shift(); | |
| if (!expectedEventQueue.length) { | |
| actor.stop(); | |
| } else { | |
| subscription = subscribe(expectedEventQueue[0]); | |
| } | |
| }); | |
| return subscription; | |
| }; | |
| subscription = subscribe(expectedEventQueue[0]); | |
| const p = xs.toPromise(actor); | |
| actor.start(); | |
| const ac = new AbortController(); | |
| return AnyActorRunner.createActorThenable( | |
| actor, | |
| Promise.race([ | |
| p.finally(() => { | |
| ac.abort(); | |
| }), | |
| scheduler.wait(timeout, {signal: ac.signal}).then(() => { | |
| const event = expectedEventQueue[0]; | |
| if (event) { | |
| throw new Error(`Event not sent in ${timeout} ms: ${event}`); | |
| } | |
| throw new Error( | |
| `All events sent in order, but actor timed out in ${timeout}ms`, | |
| ); | |
| }), | |
| ]) | |
| .then(() => { | |
| if (expectedEventQueue.length) { | |
| throw new Error( | |
| `Event(s) not sent nor emitted: ${expectedEventQueue.join(', ')}`, | |
| ); | |
| } | |
| return emitted; | |
| }) | |
| .finally(() => { | |
| subscription?.unsubscribe(); | |
| actor.stop(); | |
| }), | |
| ); | |
| } | |
| /** | |
| * Runs a actor until the snapshot predicate returns `true`. | |
| * | |
| * Immediately stops the actor thereafter. | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * @param predicate Snapshot predicate; see {@link xs.waitFor} | |
| * @param input Actor input | |
| * @param options Options | |
| * @returns {@link ActorThenable} Fulfilling with the snapshot that matches | |
| * the predicate | |
| */ | |
| public runUntilSnapshot( | |
| predicate: (snapshot: xs.SnapshotFrom<T>) => boolean, | |
| input: xs.InputFrom<T>, | |
| options?: ActorRunnerOptions, | |
| ): ActorThenable<T, xs.SnapshotFrom<T>>; | |
| /** | |
| * Runs a actor until the snapshot predicate returns `true`. | |
| * | |
| * Immediately stops the actor thereafter. | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * @param predicate Snapshot predicate; see {@link xs.waitFor} | |
| * @param input Actor | |
| * @param options Options | |
| * @returns {@link ActorThenable} Fulfilling with the snapshot that matches | |
| * the predicate | |
| */ | |
| public runUntilSnapshot( | |
| predicate: (snapshot: xs.SnapshotFrom<T>) => boolean, | |
| actor: xs.Actor<T>, | |
| options?: ActorRunnerOptionsWithActor, | |
| ): ActorThenable<T, xs.SnapshotFrom<T>>; | |
| /** | |
| * Runs an actor until the snapshot predicate returns `true`. | |
| * | |
| * Immediately stops the actor thereafter. | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * @param predicate Snapshot predicate; see {@link xs.waitFor} | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param options Options | |
| * @returns {@link ActorThenable} Fulfilling with the snapshot that matches | |
| * the predicate | |
| */ | |
| @bind() | |
| public runUntilSnapshot( | |
| predicate: (snapshot: xs.SnapshotFrom<T>) => boolean, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options: ActorRunnerOptions | ActorRunnerOptionsWithActor = {}, | |
| ): ActorThenable<T, xs.SnapshotFrom<T>> { | |
| const {timeout = this.defaultTimeout} = options; | |
| const actor = | |
| input instanceof xs.Actor | |
| ? this.instrumentActor(input, options as ActorRunnerOptionsWithActor) | |
| : this.createInstrumentedActor(input, options as ActorRunnerOptions); | |
| actor.start(); | |
| return AnyActorRunner.createActorThenable( | |
| actor, | |
| xs | |
| .waitFor(actor, predicate, {timeout}) | |
| .catch((err) => { | |
| if (err instanceof Error) { | |
| if (err.message.startsWith('Timeout of')) { | |
| throw new Error( | |
| `Snapshot did not match predicate in ${timeout}ms`, | |
| ); | |
| } else if ( | |
| err.message.startsWith( | |
| 'Actor terminated without satisfying predicate', | |
| ) | |
| ) { | |
| throw new Error(`Actor stopped without satisfying predicate`); | |
| } | |
| } | |
| throw err; | |
| }) | |
| .finally(() => { | |
| actor.stop(); | |
| }), | |
| ); | |
| } | |
| /** | |
| * Starts the actor and returns the {@link xs.Actor} object. | |
| * | |
| * @param input Actor input | |
| * @param options Options | |
| * @returns The {@link xs.Actor} itself | |
| */ | |
| public start( | |
| input: xs.InputFrom<T>, | |
| options?: Omit<ActorRunnerOptions, 'timeout'>, | |
| ): xs.Actor<T>; | |
| public start( | |
| actor: xs.Actor<T>, | |
| options?: Omit<ActorRunnerOptionsWithActor, 'timeout'>, | |
| ): xs.Actor<T>; | |
| @bind() | |
| public start( | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options: Omit< | |
| ActorRunnerOptions | ActorRunnerOptionsWithActor, | |
| 'timeout' | |
| > = {}, | |
| ): xs.Actor<T> { | |
| const actor = | |
| input instanceof xs.Actor | |
| ? this.instrumentActor(input, options as ActorRunnerOptionsWithActor) | |
| : this.createInstrumentedActor(input, options as ActorRunnerOptions); | |
| return actor.start(); | |
| } | |
| /** | |
| * A function that waits for an actor to be spawned. | |
| * | |
| * Does **not** stop the root actor. | |
| * | |
| * @param actorId A string or RegExp to match against the actor ID | |
| * @param input Actor input or an {@link xs.Actor} | |
| * @param options Options | |
| * @returns The `ActorRef` of the spawned actor | |
| */ | |
| @bind() | |
| public waitForActor<SpawnedActor extends xs.AnyActorLogic = xs.AnyActorLogic>( | |
| actorId: string | RegExp, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options: ActorRunnerOptions | ActorRunnerOptionsWithActor = {}, | |
| ): ActorThenable<T, xs.ActorRefFrom<SpawnedActor>> { | |
| const predicate = | |
| typeof actorId === 'string' | |
| ? (id: string) => id === actorId | |
| : (id: string) => actorId.test(id); | |
| const {timeout = this.defaultTimeout} = options; | |
| const actor = | |
| input instanceof xs.Actor | |
| ? this.instrumentActor(input, options as ActorRunnerOptionsWithActor) | |
| : this.createInstrumentedActor(input, options as ActorRunnerOptions); | |
| actor.start(); | |
| const ac = new AbortController(); | |
| return Object.assign( | |
| Promise.race([ | |
| new Promise<xs.ActorRefFrom<SpawnedActor>>((resolve) => { | |
| actor.system.inspect( | |
| xs.toObserver((evt) => { | |
| if (evt.type === '@xstate.actor' && predicate(evt.actorRef.id)) { | |
| resolve(evt.actorRef as xs.ActorRefFrom<SpawnedActor>); | |
| } | |
| }), | |
| ); | |
| }).finally(() => { | |
| ac.abort(); | |
| }), | |
| scheduler.wait(timeout, {signal: ac.signal}).then(() => { | |
| throw new Error( | |
| `Failed to detect an spawned actor matching ${actorId} in ${timeout}ms`, | |
| ); | |
| }), | |
| ]), | |
| actor, | |
| ); | |
| } | |
| /** | |
| * Runs a actor until the snapshot predicate returns `true`. | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * @param predicate Snapshot predicate; see {@link xs.waitFor} | |
| * @param input Actor input | |
| * @param options Options | |
| * @returns {@link ActorThenable} Fulfilling with the snapshot that matches | |
| * the predicate | |
| */ | |
| public waitForSnapshot( | |
| predicate: (snapshot: xs.SnapshotFrom<T>) => boolean, | |
| input: xs.InputFrom<T>, | |
| options?: ActorRunnerOptions, | |
| ): ActorThenable<T, xs.SnapshotFrom<T>>; | |
| /** | |
| * Runs a actor until the snapshot predicate returns `true`. | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * @param predicate Snapshot predicate; see {@link xs.waitFor} | |
| * @param input Actor | |
| * @param options Options | |
| * @returns {@link ActorThenable} Fulfilling with the snapshot that matches | |
| * the predicate | |
| */ | |
| public waitForSnapshot( | |
| predicate: (snapshot: xs.SnapshotFrom<T>) => boolean, | |
| actor: xs.Actor<T>, | |
| options?: ActorRunnerOptionsWithActor, | |
| ): ActorThenable<T, xs.SnapshotFrom<T>>; | |
| /** | |
| * Runs a new or existing actor until the snapshot predicate returns `true`. | |
| * | |
| * Returns a combination of a `Promise` and an {@link xs.Actor} so that events | |
| * may be sent to the actor. | |
| * | |
| * @param predicate Snapshot predicate; see {@link xs.waitFor} | |
| * @param input Input for {@link defaultActorLogic} or an existing {@link Actor} | |
| * @param options Options | |
| * @returns {@link ActorThenable} Fulfilling with the snapshot that matches | |
| * the predicate | |
| */ | |
| @bind() | |
| public waitForSnapshot( | |
| predicate: (snapshot: xs.SnapshotFrom<T>) => boolean, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options: ActorRunnerOptions | ActorRunnerOptionsWithActor = {}, | |
| ): ActorThenable<T, xs.SnapshotFrom<T>> { | |
| const {timeout = this.defaultTimeout} = options; | |
| const actor = | |
| input instanceof xs.Actor | |
| ? this.instrumentActor(input, options as ActorRunnerOptionsWithActor) | |
| : this.createInstrumentedActor(input, options as ActorRunnerOptions); | |
| actor.start(); | |
| return AnyActorRunner.createActorThenable( | |
| actor, | |
| xs.waitFor(actor, predicate, {timeout}).catch((err) => { | |
| if (err instanceof Error) { | |
| if (err.message.startsWith('Timeout of')) { | |
| throw new Error(`Snapshot did not match predicate in ${timeout}ms`); | |
| } else if ( | |
| err.message.startsWith( | |
| 'Actor terminated without satisfying predicate', | |
| ) | |
| ) { | |
| throw new Error(`Actor stopped before satisfying predicate`); | |
| } | |
| } | |
| throw err; | |
| }), | |
| ); | |
| } | |
| } | |
| /** | |
| * Helpers for testing state machine behavior | |
| * | |
| * @remarks | |
| * Just a wrapper around {@link AnyActorRunner} | |
| * @template T `StateMachine` actor logic | |
| */ | |
| export class StateMachineRunner<T extends xs.AnyStateMachine> | |
| implements StateMachineActorRunner<T> | |
| { | |
| constructor(public readonly runner: AnyActorRunner<T>) {} | |
| /** | |
| * {@inheritDoc AnyActorRunner.defaultActorLogic} | |
| */ | |
| public get defaultActorLogic() { | |
| return this.runner.defaultActorLogic; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.defaultId} | |
| */ | |
| public get defaultId() { | |
| return this.runner.defaultId; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.defaultInspector} | |
| */ | |
| public get defaultInspector() { | |
| return this.runner.defaultInspector; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.defaultLogger} | |
| */ | |
| public get defaultLogger() { | |
| return this.runner.defaultLogger; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.defaultTimeout} | |
| */ | |
| public get defaultTimeout() { | |
| return this.runner.defaultTimeout; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.runUntilDone} | |
| */ | |
| public get runUntilDone() { | |
| return this.runner.runUntilDone; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.runUntilEvent} | |
| */ | |
| public get runUntilEvent() { | |
| return this.runner.runUntilEvent; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.runUntilSnapshot} | |
| */ | |
| public get runUntilSnapshot() { | |
| return this.runner.runUntilSnapshot; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.start} | |
| */ | |
| public get start() { | |
| return this.runner.start; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.waitForActor} | |
| */ | |
| public get waitForActor() { | |
| return this.runner.waitForActor; | |
| } | |
| /** | |
| * {@inheritDoc AnyActorRunner.waitForSnapshot} | |
| */ | |
| public get waitForSnapshot() { | |
| return this.runner.waitForSnapshot; | |
| } | |
| /** | |
| * Runs the machine until a transition from the `source` state to the `target` | |
| * state occurs. | |
| * | |
| * Immediately stops the machine thereafter. Returns a combination of a | |
| * `Promise` and an {@link xs.Actor} so that events may be sent to the actor. | |
| * | |
| * @param source Source state ID | |
| * @param target Target state ID | |
| * @param input Machine input | |
| * @param opts Options | |
| * @returns An {@link ActorThenable} that resolves when the specified | |
| * transition occurs | |
| * @todo Type narrowing for `source` and `target` once xstate supports it | |
| * | |
| * @todo Attempt to reuse {@link waitUntilTransition} | |
| */ | |
| @bind() | |
| public runUntilTransition( | |
| source: string, | |
| target: string, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options: OptionsWithoutInspect< | |
| ActorRunnerOptions | ActorRunnerOptionsWithActor | |
| > = {}, | |
| ): ActorThenable<T> { | |
| const {timeout = this.defaultTimeout} = options; | |
| let sawTransition = false; | |
| /** | |
| * We need the actor ID here so we can match against it in the inspector. | |
| * However, we don't necessarily have an actor yet, and the inspector may | |
| * fire _before_ we do (think: initial transition). But we also don't want | |
| * to miss anything, so we need to generate an ID unless one is otherwise | |
| * provided. | |
| */ | |
| const id = this.runner.getActorId( | |
| input, | |
| (options as OptionsWithoutInspect<ActorRunnerOptions>).id, | |
| ); | |
| const transitionInspector = (evt: xs.InspectionEvent) => { | |
| if (evt.type === '@xstate.microstep') { | |
| if (evt.actorRef.id === id) { | |
| if ( | |
| evt._transitions.some( | |
| (tDef) => | |
| tDef.source.id === source && | |
| tDef.target?.some((t) => t.id === target), | |
| ) | |
| ) { | |
| sawTransition = true; | |
| } | |
| } | |
| } | |
| }; | |
| const actor = | |
| input instanceof xs.Actor | |
| ? this.runner.instrumentActor(input, { | |
| ...options, | |
| inspect: transitionInspector, | |
| } as ActorRunnerOptionsWithActor) | |
| : this.runner.createInstrumentedActor(input, { | |
| ...options, | |
| id, | |
| inspect: transitionInspector, | |
| } as ActorRunnerOptions); | |
| // @ts-expect-error internal | |
| const {idMap} = this.runner.defaultActorLogic; | |
| if (!idMap.has(source)) { | |
| throw new Error(`Unknown state ID (source): ${source}`); | |
| } | |
| if (!idMap.has(target)) { | |
| throw new Error(`Unknown state ID (target): ${target}`); | |
| } | |
| const p = xs.toPromise(actor); | |
| const ac = new AbortController(); | |
| actor.start(); | |
| return AnyActorRunner.createActorThenable( | |
| actor, | |
| Promise.race([ | |
| p.then(noop, noop).finally(() => { | |
| ac.abort(); | |
| }), | |
| scheduler.wait(timeout, {signal: ac.signal}).then(() => { | |
| throw new Error( | |
| `Failed to detect a transition from ${source} to ${target} in ${timeout}ms`, | |
| ); | |
| }), | |
| ]) | |
| .then(() => { | |
| if (!sawTransition) { | |
| throw new Error( | |
| `Transition from ${source} to ${target} not detected`, | |
| ); | |
| } | |
| }) | |
| .finally(() => { | |
| actor.stop(); | |
| }), | |
| ); | |
| } | |
| /** | |
| * Runs the machine until a transition from the `source` state to the `target` | |
| * state occurs. | |
| * | |
| * Useful for chaining transitions--but keep in mind that actions are executed | |
| * synchronously! | |
| * | |
| * **Does not stop the machine**. Returns a combination of a `Promise` and an | |
| * {@link xs.Actor} so that events may be sent to the actor. | |
| * | |
| * @param source Source state ID | |
| * @param target Target state ID | |
| * @param input Machine input | |
| * @param opts Options | |
| * @returns An {@link ActorThenable} that resolves when the specified | |
| * transition occurs | |
| * @todo Type narrowing for `source` and `target` once xstate supports it | |
| */ | |
| @bind() | |
| public waitForTransition( | |
| source: string, | |
| target: string, | |
| input: xs.InputFrom<T> | xs.Actor<T>, | |
| options: OptionsWithoutInspect< | |
| ActorRunnerOptions | ActorRunnerOptionsWithActor | |
| > = {}, | |
| ): ActorThenable<T> { | |
| const {timeout = this.defaultTimeout} = options; | |
| let sawTransition = false; | |
| /** | |
| * We need the actor ID here so we can match against it in the inspector. | |
| * However, we don't necessarily have an actor yet, and the inspector may | |
| * fire _before_ we do (think: initial transition). But we also don't want | |
| * to miss anything, so we need to generate an ID unless one is otherwise | |
| * provided. | |
| */ | |
| const id = this.runner.getActorId( | |
| input, | |
| (options as OptionsWithoutInspect<ActorRunnerOptions>).id, | |
| ); | |
| const transitionInspector = (evt: xs.InspectionEvent) => { | |
| if (evt.type === '@xstate.microstep') { | |
| if (evt.actorRef.id === id) { | |
| if ( | |
| evt._transitions.some( | |
| (tDef) => | |
| tDef.source.id === source && | |
| tDef.target?.some((t) => t.id === target), | |
| ) | |
| ) { | |
| sawTransition = true; | |
| evt.actorRef.stop(); | |
| } | |
| } | |
| } | |
| }; | |
| const actor = | |
| input instanceof xs.Actor | |
| ? this.runner.instrumentActor(input, { | |
| ...options, | |
| inspect: transitionInspector, | |
| } as ActorRunnerOptionsWithActor) | |
| : this.runner.createInstrumentedActor(input, { | |
| ...options, | |
| id, | |
| inspect: transitionInspector, | |
| } as ActorRunnerOptions); | |
| // @ts-expect-error internal | |
| const {idMap} = this.runner.defaultActorLogic; | |
| if (!idMap.has(source)) { | |
| throw new Error(`Unknown state ID (source): ${source}`); | |
| } | |
| if (!idMap.has(target)) { | |
| throw new Error(`Unknown state ID (target): ${target}`); | |
| } | |
| const p = xs.toPromise(actor); | |
| const ac = new AbortController(); | |
| actor.start(); | |
| return AnyActorRunner.createActorThenable( | |
| actor, | |
| Promise.race([ | |
| p.then(noop, noop).finally(() => { | |
| ac.abort(); | |
| }), | |
| scheduler.wait(timeout, {signal: ac.signal}).then(() => { | |
| throw new Error( | |
| `Failed to detect a transition from ${source} to ${target} in ${timeout}ms`, | |
| ); | |
| }), | |
| ]).then(() => { | |
| if (!sawTransition) { | |
| throw new Error( | |
| `Transition from ${source} to ${target} not detected`, | |
| ); | |
| } | |
| }), | |
| ); | |
| } | |
| } | |
| /** | |
| * Decorator to bind a class method to a context (defaulting to `this`) | |
| * | |
| * @param ctx Alternate context, if needed | |
| */ | |
| export function bind< | |
| TThis extends object, | |
| TArgs extends any[] = unknown[], | |
| TReturn = unknown, | |
| TContext extends object = TThis, | |
| >(ctx?: TContext) { | |
| return function ( | |
| target: (this: TThis, ...args: TArgs) => TReturn, | |
| context: ClassMethodDecoratorContext< | |
| TThis, | |
| (this: TThis, ...args: TArgs) => TReturn | |
| >, | |
| ) { | |
| context.addInitializer(function (this: TThis) { | |
| const func = context.access.get(this); | |
| // @ts-expect-error FIXME | |
| this[context.name] = func.bind(ctx ?? this); | |
| }); | |
| }; | |
| } | |
| export function createActorRunner<T extends xs.AnyStateMachine>( | |
| stateMachine: T, | |
| options?: ActorRunnerOptions, | |
| ): StateMachineRunner<T>; | |
| export function createActorRunner<T extends xs.AnyActorLogic>( | |
| actorLogic: T, | |
| options?: ActorRunnerOptions, | |
| ): AnyActorRunner<T>; | |
| export function createActorRunner< | |
| T extends xs.AnyActorLogic | xs.AnyStateMachine, | |
| >(actorLogic: T, options?: ActorRunnerOptions) { | |
| if (isStateMachine(actorLogic)) { | |
| const runner = AnyActorRunner.create(actorLogic, options); | |
| return new StateMachineRunner(runner); | |
| } | |
| return AnyActorRunner.create(actorLogic, options); | |
| } | |
| /** | |
| * Type guard to determine if some actor logic is a state machine | |
| * | |
| * @param actorLogic Any actor logic | |
| * @returns `true` if `actorLogic` is a state machine | |
| */ | |
| export function isStateMachine<T extends xs.AnyActorLogic>( | |
| actorLogic: T, | |
| ): actorLogic is T & xs.AnyStateMachine { | |
| return actorLogic instanceof xs.StateMachine; | |
| } | |
| /** | |
| * That's a no-op, folks | |
| */ | |
| const noop = () => {}; | |
| /** | |
| * Default timeout (in ms) for any of the "run until" methods in | |
| * {@link AnyActorRunner} | |
| * | |
| * This must be set to a lower value than the default timeout for the test | |
| * runner. | |
| */ | |
| const DEFAULT_TIMEOUT = 1000; |