{"id":15598163,"url":"https://github.com/boneskull/xstate-audition","last_synced_at":"2025-09-13T18:32:46.577Z","repository":{"id":251557758,"uuid":"837758258","full_name":"boneskull/xstate-audition","owner":"boneskull","description":"Test Actor behavior in XState v5","archived":false,"fork":false,"pushed_at":"2025-01-02T23:41:41.000Z","size":1013,"stargazers_count":17,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-03T00:25:19.064Z","etag":null,"topics":["actor","state-machine","state-management","statecharts","test","test-automation","testing","xstate"],"latest_commit_sha":null,"homepage":"https://boneskull.github.io/xstate-audition/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boneskull.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"boneskull"}},"created_at":"2024-08-04T00:03:02.000Z","updated_at":"2025-01-02T23:41:44.000Z","dependencies_parsed_at":"2024-08-27T02:51:43.820Z","dependency_job_id":"24479cba-7e0f-40c5-82aa-bb6528f538e8","html_url":"https://github.com/boneskull/xstate-audition","commit_stats":{"total_commits":201,"total_committers":3,"mean_commits":67.0,"dds":"0.37810945273631846","last_synced_commit":"8393ad7453d2ce04b2c5722d873fbaf5f5e6834f"},"previous_names":["boneskull/xstate-audition"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fxstate-audition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fxstate-audition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fxstate-audition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boneskull%2Fxstate-audition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boneskull","download_url":"https://codeload.github.com/boneskull/xstate-audition/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232902856,"owners_count":18594353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actor","state-machine","state-management","statecharts","test","test-automation","testing","xstate"],"created_at":"2024-10-03T01:29:20.751Z","updated_at":"2025-01-07T15:59:06.950Z","avatar_url":"https://github.com/boneskull.png","language":"TypeScript","funding_links":["https://github.com/sponsors/boneskull"],"categories":[],"sub_categories":[],"readme":"# xstate-audition\n\n\u003e Harnesses for testing XState v5 Actors. Actor test...audition...get it??\n\n**xstate-audition** is a _dependency-free_ library for testing the behavior of [XState Actors][].\n\n[**API Documentation**](https://boneskull.github.io/xstate-audition) |\n[**GitHub**](https://github.com/boneskull/xstate-audition) |\n[**npm**](https://npm.im/xstate-audition)\n\n---\n\n- [Usage \\\u0026 Examples](#usage--examples)\n  - [`runUntilDone(actor)`](#rununtildoneactor)\n  - [`runUntilEmitted(actor, emittedTypes)`](#rununtilemittedactor-emittedtypes)\n  - [`runUntilTransition(actor, fromStateId, toStateId)`](#rununtiltransitionactor-fromstateid-tostateid)\n  - [`runUntilSnapshot(actor, predicate)`](#rununtilsnapshotactor-predicate)\n  - [`runUntilSpawn(actor, childId)`](#rununtilspawnactor-childid)\n  - [`runUntilEventReceived(actor, eventTypes)`](#rununtileventreceivedactor-eventtypes)\n  - [`runUntilEventSent()`](#rununtileventsent)\n  - [`createActorFromLogic(logic, options)`](#createactorfromlogiclogic-options)\n  - [`createActorWith(options, logic)`](#createactorwithoptions-logic)\n  - [`patchActor(actor, options)`](#patchactoractor-options)\n  - [`unpatchActor(actor)`](#unpatchactoractor)\n  - [`AuditionOptions`](#auditionoptions)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [API Notes](#api-notes)\n- [License](#license)\n- [Disclaimer](#disclaimer)\n\n---\n\n## Usage \u0026 Examples\n\n**TL;DR:**\n\n1. Create an `Actor` using `xstate.createActor(logic)`.\n2. Create a `Promise\u003cT\u003e` using one of the functions below (e.g., `runUntilDone(actor: Actor) =\u003e Promise\u003cT\u003e` where `T` is the _Actor output_). If the actor hadn't yet been started, it will be started now.\n3. _If_ your actor needs external input to resolve the condition (e.g., it must receive an event), perform that operation _before_ you `await` the `Promise\u003cT\u003e` (examples below).\n4. Now, you can `await` the `Promise\u003cT\u003e` from step 2.\n5. Finally, make an assertion about `T`.\n\n### `runUntilDone(actor)`\n\n_Run a Promise Actor or State Machine to Completion_\n\n#### API Docs\n\n- [`runUntilDone(actor)`](https://boneskull.github.io/xstate-audition/functions/runUntilDone.html)\n- [`runUntilDoneWith(actor, options)`](https://boneskull.github.io/xstate-audition/functions/runUntilDoneWith.html)\n- [`waitForDone(actor)`](https://boneskull.github.io/xstate-audition/functions/waitForDone.html)\n- [`waitForDoneWith(actor, options)`](https://boneskull.github.io/xstate-audition/functions/waitForDoneWith.html)\n\n#### Description\n\n`runUntilDone(actor)` / `runUntilDoneWith(actor, options)` are curried functions that will start a [Promise Actor][] or [State Machine Actor][] and run it until it reaches a final state. Once the `Actor` reaches a final state, it will immediately be stopped. The `Promise` will be resolved with the output of the `Actor`.\n\n\u003e [!NOTE]\n\u003e\n\u003e - `runUntilDone()` is not significantly different than XState's `toPromise()`.\n\u003e - `runUntilDoneWith()` may be used to overwrite the internal logger and/or add an inspector callback (or `Observer`) to an `Actor`.\n\u003e - _There is no such_ `waitForDone(...)` / `waitForDoneWith(...)` variant, since that would be silly.\n\n#### Example\n\n```ts\nimport {strict as assert} from 'node:assert';\nimport {beforeEach, describe, it} from 'node:test';\nimport {type Actor, createActor, fromPromise} from 'xstate';\n\nimport {runUntilDone, runUntilDoneWith} from 'xstate-audition';\n\nconst promiseLogic = fromPromise\u003cstring, string\u003e(\n  // this signal is aborted via call to Actor.stop()\n  async ({input, signal}) =\u003e {\n    let listener!: () =\u003e void;\n    try {\n      return await new Promise((resolve, reject) =\u003e {\n        listener = () =\u003e {\n          clearTimeout(timeout);\n          // this rejection is eaten by xstate-audition\n          // in lieu of its own timeout error (seen below)\n          reject(signal.reason);\n        };\n\n        const timeout = setTimeout(() =\u003e {\n          resolve(`hello ${input}`);\n        }, 500);\n\n        signal.addEventListener('abort', listener);\n      });\n    } finally {\n      signal.removeEventListener('abort', listener);\n    }\n  },\n);\n\ndescribe('logic', () =\u003e {\n  let actor: Actor\u003ctypeof promiseLogic\u003e;\n\n  beforeEach(() =\u003e {\n    actor = createActor(promiseLogic, {input: 'world'});\n  });\n\n  it('should output with the expected value', async () =\u003e {\n    const result = await runUntilDone(actor);\n\n    assert.equal(result, 'hello world');\n  });\n\n  it('should abort when provided a too-short timeout', async () =\u003e {\n    await assert.rejects(\n      runUntilDoneWith(actor, {timeout: 100}),\n      (err: Error) =\u003e {\n        assert.equal(err.message, 'Actor did not complete in 100ms');\n\n        return true;\n      },\n    );\n  });\n});\n```\n\n### `runUntilEmitted(actor, emittedTypes)`\n\n_Run a State Machine Until It Emits Events_\n\n#### API Docs\n\n- [`runUntilEmitted(actor, emittedTypes)`](https://boneskull.github.io/xstate-audition/functions/runUntilEmitted.html)\n- [`runUntilEmittedWith(actor, options, emittedTypes)`](https://boneskull.github.io/xstate-audition/functions/runUntilEmittedWith.html)\n- [`waitForEmitted(actor, emittedTypes)`](https://boneskull.github.io/xstate-audition/functions/waitForEmitted.html)\n- [`waitForEmittedWith(actor, options, emittedTypes)`](https://boneskull.github.io/xstate-audition/functions/waitForEmittedWith.html)\n\n#### Description\n\n`runUntilEmitted(actor, eventTypes)` / `runUntilEmittedWith(actor, options, eventTypes)` are curried function that will start an `Actor` and run it until emits one or more events of the specified `type`. Once the events have been emitted, the actor will immediately be stopped.\n\n`waitForEmitted(actor, eventTypes)` / `waitForEmittedWith(actor, options, eventTypes)` are similar, but do not stop the actor.\n\n\u003e [!NOTE]\n\u003e\n\u003e This function _only_ applies to events emitted via the [event emitter API][event-emitter].\n\n#### Example\n\n```ts\nimport {strict as assert} from 'node:assert';\nimport {beforeEach, describe, it} from 'node:test';\nimport {type Actor, createActor, emit, setup} from 'xstate';\n\nimport {type CurryEmittedP1, runUntilEmitted} from 'xstate-audition';\n\ntype Emit1 = {type: 'EMIT1'; value: string};\n\ntype Emit2 = {type: 'EMIT2'; value: number};\n\ntype EmitterEmitted = Emit1 | Emit2;\n\nconst emitterMachine = setup({\n  types: {\n    emitted: {} as EmitterEmitted,\n  },\n}).createMachine({\n  entry: [\n    emit({type: 'EMIT1', value: 'value'}),\n    emit({type: 'EMIT2', value: 42}),\n  ],\n});\n\ndescribe('emitterMachine', () =\u003e {\n  let actor: Actor\u003ctypeof emitterMachine\u003e;\n\n  let runUntilEmit: CurryEmittedP1\u003ctypeof actor\u003e;\n\n  beforeEach(() =\u003e {\n    actor = createActor(emitterMachine);\n\n    // runUntilEmitted is curried, so could be called with [actor, ['EMIT1', 'EMIT2']]\n    // instead\n    runUntilEmit = runUntilEmitted(actor);\n  });\n\n  it('should emit two events', async () =\u003e {\n    const [emit1Event, emit2Event] = await runUntilEmit(['EMIT1', 'EMIT2']);\n\n    assert.deepEqual(emit1Event, {type: 'EMIT1', value: 'value'});\n    assert.deepEqual(emit2Event, {type: 'EMIT2', value: 42});\n  });\n});\n```\n\n### `runUntilTransition(actor, fromStateId, toStateId)`\n\n_Run a State Machine Until It Transitions from One State to Another_\n\n#### API Docs\n\n- [`runUntilTransition(actor, fromStateId, toStateId)`](https://boneskull.github.io/xstate-audition/functions/runUntilTransition.html)\n- [`runUntilTransitionWith(actor, options, fromStateId, toStateId)`](https://boneskull.github.io/xstate-audition/functions/runUntilTransitionWith.html)\n- [`waitForTransition(actor, fromStateId, toStateId)`](https://boneskull.github.io/xstate-audition/functions/waitForTransition.html)\n- [`waitForTransitionWith(actor, options, fromStateId, toStateId)`](https://boneskull.github.io/xstate-audition/functions/waitForTransitionWith.html)\n\n#### Description\n\n`runUntilTransition(actor, fromStateId, toStateId)` / `runUntilTransitionWith(actor, options, fromStateId, toStateId)` are curried functions that will start an `Actor` and run it until it transitions from state with ID `fromStateId` to state with ID `toStateId`. Once the `Actor` transitions to the specified state, it will immediately be stopped.\n\n`waitForTransition(actor, fromStateId, toStateId)` / `waitForStateWith(actor, options, fromStateId, toStateId)` are similar, but do not stop the `Actor`.\n\n#### Example\n\n```ts\nimport {strict as assert} from 'node:assert';\nimport {beforeEach, describe, it} from 'node:test';\nimport {type Actor, createActor, createMachine} from 'xstate';\n\nimport {type CurryTransitionP2, runUntilTransition} from '../src/index.js';\n\nconst transitionMachine = createMachine({\n  // if you do not supply a default ID, then the ID will be `(machine)`\n  id: 'transitionMachine',\n  initial: 'first',\n  states: {\n    first: {\n      after: {\n        100: 'second',\n      },\n    },\n    second: {\n      after: {\n        100: 'third',\n      },\n    },\n    third: {\n      type: 'final',\n    },\n  },\n});\n\ndescribe('transitionMachine', () =\u003e {\n  let actor: Actor\u003ctypeof transitionMachine\u003e;\n\n  let runWithFirst: CurryTransitionP2\u003ctypeof actor\u003e;\n\n  beforeEach(() =\u003e {\n    actor = createActor(transitionMachine);\n    // curried\n    runWithFirst = runUntilTransition(actor, 'transitionMachine.first');\n  });\n\n  it('should transition from \"first\" to \"second\"', async () =\u003e {\n    await runWithFirst('transitionMachine.second');\n  });\n\n  it('should not transition from \"first\" to \"third\"', async () =\u003e {\n    await assert.rejects(runWithFirst('transitionMachine.third'));\n  });\n});\n```\n\n### `runUntilSnapshot(actor, predicate)`\n\n_Run a Actor Until It Satisfies a Snapshot Predicate_\n\n#### API Docs\n\n- [`runUntilSnapshot(actor, predicate)`](https://boneskull.github.io/xstate-audition/functions/runUntilSnapshot.html)\n- [`runUntilSnapshotWith(actor, options, predicate)`](https://boneskull.github.io/xstate-audition/functions/runUntilSnapshotWith.html)\n- [`waitForSnapshot(actor, predicate)`](https://boneskull.github.io/xstate-audition/functions/waitForSnapshot.html)\n- [`waitForSnapshotWith(actor, options, predicate)`](https://boneskull.github.io/xstate-audition/functions/waitForSnapshotWith.html)\n\n#### Description\n\n`runUntilSnapshot(actor, predicate)` / `runUntilSnapshotWith(actor, options,  predicate)` are curried functions that will start an `Actor` and run it until the actor's [Snapshot][snapshot] satisfies `predicate` (which is the same type as the `predicate` parameter of [`xstate.waitFor()`][waitFor]). Once the snapshot matches the predicate, the actor will immediately be stopped.\n\n\u003e [!NOTE]\n\u003e\n\u003e - Like [`runUntilDone()`][runUntilDone], `runUntilSnapshot()` is not significantly different than XState's `waitFor()`.\n\u003e - `runUntilSnapshotWith()` may be used to overwrite the internal logger and/or add an inspector callback (or `Observer`) to an Actor.\n\n#### Example\n\n```ts\nimport {strict as assert} from 'node:assert';\nimport {describe, it} from 'node:test';\nimport {assign, createActor, setup} from 'xstate';\n\nimport {runUntilSnapshot} from 'xstate-audition';\n\nconst snapshotLogic = setup({\n  types: {\n    context: {} as {word?: string},\n  },\n}).createMachine({\n  initial: 'first',\n  states: {\n    done: {\n      type: 'final',\n    },\n    first: {\n      after: {\n        50: 'second',\n      },\n      entry: assign({\n        word: 'foo',\n      }),\n    },\n    second: {\n      after: {\n        50: 'third',\n      },\n      entry: assign({\n        word: 'bar',\n      }),\n    },\n    third: {\n      after: {\n        50: 'done',\n      },\n      entry: assign({\n        word: 'baz',\n      }),\n    },\n  },\n});\n\ndescribe('snapshotLogic', () =\u003e {\n  it('should contain word \"bar\" in state \"second\"', async () =\u003e {\n    const actor = createActor(snapshotLogic);\n\n    const snapshot = await runUntilSnapshot(actor, (snapshot) =\u003e\n      snapshot.matches('second'),\n    );\n\n    assert.deepEqual(snapshot.context, {word: 'bar'});\n  });\n\n  it('should be in state \"second\" when word is \"bar\"', async () =\u003e {\n    const actor = createActor(snapshotLogic);\n\n    const snapshot = await runUntilSnapshot(\n      actor,\n      (snapshot) =\u003e snapshot.context.word === 'bar',\n    );\n\n    assert.equal(snapshot.value, 'second');\n  });\n});\n```\n\n### `runUntilSpawn(actor, childId)`\n\n_Run a State Machine Actor Until Its System Spawns a Child Actor_\n\n#### API Docs\n\n- [`runUntilSpawn(actor, childId)`](https://boneskull.github.io/xstate-audition/functions/runUntilSpawn.html)\n- [`runUntilSpawnWith(actor, options, childId)`](https://boneskull.github.io/xstate-audition/functions/runUntilSpawnWith.html)\n- [`waitForSpawn(actor, childId)`](https://boneskull.github.io/xstate-audition/functions/waitForSpawn.html)\n- [`waitForSpawnWith(actor, options, childId)`](https://boneskull.github.io/xstate-audition/functions/waitForSpawnWith.html)\n\n#### Description\n\n`runUntilSpawn(actor, childId)` / `runUntilSpawnWith(actor, options, childId)` are curried functions that will start an `Actor` and run it until it spawns a child `ActorRef` with `id` matching `childId` (which may be a `RegExp`). Once the child `ActorRef` is spawned, the `Actor` will immediately be stopped. The `Promise` will be resolved with a reference to the spawned `ActorRef` (an `AnyActorRef` by default).\n\n`waitForSpawn(actor, childId)` / `waitForSpawnWith(actor, options, childId)` are similar, but do not stop the actor.\n\nThe root State Machine actor itself needn't spawn the child with the matching `id`, but _any_ `ActorRef` within the root actor's system may spawn the child.\n\n\u003e [!NOTE]\n\u003e\n\u003e - The _type_ of the spawned `ActorRef` cannot be inferred by ID alone. For this reason, it's recommended to _provide an explicit type argument_ to `runUntilSpawn` (and variants) declaring the type of the spawned `ActorRef`'s `ActorLogic`, as seen in the below example.\n\u003e - As of this writing, there is no way to specify the _parent_ of the spawned `ActorRef`.\n\n#### Example\n\n```ts\nimport {strict as assert} from 'node:assert';\nimport {describe, it} from 'node:test';\nimport {createActor, fromPromise, setup, spawnChild} from 'xstate';\n\nimport {waitForSpawn} from 'xstate-audition';\n\nconst noopPromiseLogic = fromPromise\u003cvoid, void\u003e(async () =\u003e {});\n\nconst spawnerMachine = setup({\n  actors: {noop: noopPromiseLogic},\n  types: {events: {} as {type: 'SPAWN'}},\n}).createMachine({\n  on: {\n    SPAWN: {\n      actions: spawnChild('noop', {id: 'noopPromise'}),\n    },\n  },\n});\n\ndescribe('spawnerMachine', () =\u003e {\n  it('should spawn a child with ID \"noopPromise\" when \"SPAWN\" event received', async () =\u003e {\n    const actor = createActor(spawnerMachine);\n\n    try {\n      // spawnerMachine needs an event to spawn the actor. but at this point,\n      // the actor hasn't started, so we cannot send the event because nothing\n      // will be listening for it.\n      //\n      // but if we start the actor ourselves \u0026 send the event, spawning could\n      // happen before waitForSpawn can detect it! so instead of immediately\n      // awaiting, let's just set it up first.\n      const promise = waitForSpawn\u003ctypeof noopPromiseLogic\u003e(\n        actor,\n        'noopPromise',\n      );\n\n      // the detection is now setup and the actor is active; the code running in\n      // the Promise is waiting for the spawn to occur. so let's oblige it:\n      actor.send({type: 'SPAWN'});\n\n      // ...then we can finally await the promise.\n      const actorRef = await promise;\n\n      assert.equal(actorRef.id, 'noopPromise');\n    } finally {\n      // you can shutdown manually! for fun!\n      actor.stop();\n    }\n  });\n});\n```\n\n### `runUntilEventReceived(actor, eventTypes)`\n\n_Run an Actor Until It Receives an Event_\n\n#### API Docs\n\n- [`runUntilEventReceived(actor, eventTypes)`](https://boneskull.github.io/xstate-audition/functions/runUntilEventReceived.html)\n- [`runUntilEventReceivedWith(actor, options, eventTypes)`](https://boneskull.github.io/xstate-audition/functions/runUntilEventReceivedWith.html)\n- [`waitForEventReceived(actor, eventTypes)`](https://boneskull.github.io/xstate-audition/functions/waitForEventReceived.html)\n- [`waitForEventReceivedWith(actor, options, eventTypes)`](https://boneskull.github.io/xstate-audition/functions/waitForEventReceivedWith.html)\n\n#### Description\n\n`runUntilEventReceived(actor, eventTypes)` / `runUntilEventReceivedWith(actor, options, eventTypes)` are curried functions that will start a [State Machine Actor][], [Callback Actor][], or [Transition Actor][] and run it until it receives event(s) of the specified `type`. Once the event(s) are received, the actor will immediately be stopped. The `Promise` will be resolved with the received event(s).\n\n`runUntilEventReceived()`'s `options` parameter accepts an `otherActorId` (`string` or `RegExp`) property. If set, this will ensure the event was _received from_ the actor with ID matching `otherActorId`.\n\n`withForEventReceived(actor, eventTypes)` / `waitForEventReceivedWith(actor, options, eventTypes)` are similar, but do not stop the actor.\n\nUsage is similar to [`runUntilEmitted()`](#rununtilemittedactor-emittedtypes)—with the exception of the `otherActorId` property as described above.\n\n### `runUntilEventSent()`\n\n_Run an Actor Until It Sends an Event_\n\n#### API Docs\n\n- [`runUntilEventSent(actor, eventTypes)`](https://boneskull.github.io/xstate-audition/functions/runUntilEventSent.html)\n- [`runUntilEventSentWith(actor, options, eventTypes)`](https://boneskull.github.io/xstate-audition/functions/runUntilEventSentWith.html)\n- [`waitForEventSent(actor, eventTypes)`](https://boneskull.github.io/xstate-audition/functions/waitForEventSent.html)\n- [`waitForEventSentWith(actor, options, eventTypes)`](https://boneskull.github.io/xstate-audition/functions/waitForEventSentWith.html)\n\n#### Description\n\n`runUntilEventSent(actor, eventTypes)` / `runUntilEventSentWith(actor, options, eventTypes)` are curried functions that will start an `Actor` and run it until it sends event(s) of the specified `type`. Once the event(s) are sent, the actor will immediately be stopped. The `Promise` will be resolved with the sent event(s).\n\n`runUntilEventSentWith()`'s `options` parameter accepts an `otherActorId` (`string` or `RegExp`) property. If set, this will ensure the event was _sent to_ the actor with ID matching `otherActorId`.\n\n`waitForEventSent(actor, eventTypes)` / `waitForEventSentWith(actor, options, eventTypes)` are similar, but do not stop the actor.\n\nUsage is similar to [`runUntilEmitted()`](#rununtilemittedactor-emittedtypes)—with the exception of the `otherActorId` property as described above.\n\n### `createActorFromLogic(logic, options)`\n\n_Curried Function to Create an Actor from Logic_\n\n#### API Docs\n\n- [`createActorFromLogic(logic, options)`](https://boneskull.github.io/xstate-audition/functions/createActorFromLogic.html)\n\n#### Description\n\nA convenience function for when you find yourself repeatedly creating the same actor with different input.\n\nSee also [`createActorWith()`](#createactorwithoptions-logic).\n\n#### Example\n\n```ts\nconst createActor = createActorFromLogic(myLogic);\n\nit('should do x with input y', () =\u003e {\n  const actor = createActor({input: 'y'});\n  // ...\n});\n\nit('should do x2 with input z', () =\u003e {\n  const actor = createActor({input: 'z'});\n  // ...\n});\n```\n\n### `createActorWith(options, logic)`\n\n_Curried Function to Create an Actor with Options_\n\n#### API Docs\n\n- [`createActorWith(options, logic)`](https://boneskull.github.io/xstate-audition/functions/createActorWith.html)\n\n#### Description\n\nA function for when you find yourself repeatedly creating different actors with the same input.\n\nSee also [`createActorFromLogic()`](#createactorfromlogiclogic-options).\n\n#### Example\n\n```ts\nconst createYActor = createActorWith({input: 'y'}});\n\nit('should do x with FooMachine', () =\u003e {\n  const actor = createYActor(fooMachine);\n  // ...\n});\n\nit('should do x2 with BarMachine', () =\u003e {\n  const actor = createYActor(barMachine);\n  // ...\n});\n```\n\n### `patchActor(actor, options)`\n\n_Modify an Actor for Use with **xstate-audition**_\n\n#### API Docs\n\n- [`patchActor(actor, options)`](https://boneskull.github.io/xstate-audition/functions/patchActor.html)\n\nThis is used internally by all of the other curried functions to ~~violate~~ mutate existing actors. You shouldn't need to use it, but it's there if you want to.\n\n### `unpatchActor(actor)`\n\n_Revert Modifications Made to an Actor by **xstate-audition**_\n\n#### API Docs\n\n- [`unpatchActor(actor)`](https://boneskull.github.io/xstate-audition/functions/unpatchActor.html)\n\n#### Description\n\n\u003e [!WARNING]\n\u003e\n\u003e _This function is experimental and may be removed in a future release._\n\n`unpatchActor(actor)` will \"undo\" what **xstate-inspector** did in [patchActor](#patchactoractor-options).\n\nIf **xstate-audition** has never mutated the `Actor`, this function is a no-op.\n\n### `AuditionOptions`\n\n_Options for many **xstate-audition** Functions_\n\n#### API Docs\n\n- [`AuditionOptions`](https://boneskull.github.io/xstate-audition/types/AuditionOptions.html)\n\n#### Description\n\nIf you want to attach your own inspector, use a different logger, or set a different timeout, you can use `AuditionOptions`.\n\nIt bears repeating: all functions ending in `With()` accept an `AuditionOptions` object as the _second_ argument. **If the function name doesn't end with `With()`, it does not accept an `AuditionOptions` object.**\n\nThe `AuditionOptions` object may contain the following properties:\n\n- **`inspector`** - `((event: xstate.InspectionEvent) =\u003e void) | xstate.Observer\u003cxstate.InspectionEvent\u003e`: An inspector callback or observer to attach to the actor. This _will not_ overwrite any existing inspector, but may be \"merged\" with any inspector used internally by **xstate-audition**.\n\n  The behavior is similar to setting the `inspect` option when calling `xstate.createActor()`.\n\n- **`logger`** - `(args: ...any[]) =\u003e void`: **Default: no-op** (no logging; XState defaults to `console.log`). Set the logger of the Actor.\n\n  The behavior is similar to setting the `logger` option when calling `xstate.createActor()`; _however_, this logger ~~will~~ should cascade to all child actors.\n\n- **`timeout`** - `number`: **Default: 1000ms**. The maximum number of milliseconds to wait for the actor to satisfy the condition. If the actor does not satisfy the condition within this time, the `Promise` will be rejected.\n\n  A `timeout` of `0`, a negative number, or `Infinity` will disable the timeout.\n\n  _The value of `timeout` should be less than the test timeout!_\n\n## Requirements\n\n- Node.js v20.0.0+ or modern browser\n- `xstate` v5+\n\n\u003e [!CAUTION]\n\u003e\n\u003e Haven't tested the browser yet, but there are no dependencies on Node.js builtins.\n\n## Installation\n\n[xstate](https://npm.im/xstate) v5+ is a peer dependency of **xstate-audition**.\n\n```sh\nnpm install xstate-audition -D\n```\n\n## API Notes\n\n- All functions exposed by **xstate-audition**'s are curried. The final return type of each function is `Promise\u003cT\u003e`.\n- All functions ending in `With()` accept an [`AuditionOptions`](#auditionoptions) object as the _second_ argument. **If the function name doesn't end with `With()`, it does not accept an `AuditionOptions` object** (excepting [`createActorFromLogic`](#createactorfromlogiclogic-options)).\n- Any inspectors _already attached_ to an `Actor` provided to **xstate-audition** will be preserved.\n- At this time, **xstate-audition** offers no mechanism to set global defaults for [`AuditionOptions`][AuditionOptions].\n\n## License\n\n©️ 2024 [Christopher \"boneskull\" Hiller][boneskull]. Licensed Apache-2.0.\n\n## Disclaimer\n\n_This project is not affiliated with nor endorsed by [Stately.ai](https://stately.ai)._\n\n[promise actor]: https://stately.ai/docs/actors#frompromise\n[state machine actor]: https://stately.ai/docs/actors#createmachine\n[callback actor]: https://stately.ai/docs/actors#fromcallback\n[transition actor]: https://stately.ai/docs/actors#fromtransition\n[waitFor]: https://stately.ai/blog/2022-05-03-whats-new-may-2022#waitfor\n[XState actors]: https://stately.ai/docs/category/actors\n[snapshot]: https://stately.ai/docs/actors#actor-snapshots\n[AuditionOptions]: #auditionoptions\n[runUntilDone]: #rununtildoneactor\n[boneskull]: https://github.com/boneskull\n[event-emitter]: https://stately.ai/docs/event-emitter\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboneskull%2Fxstate-audition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboneskull%2Fxstate-audition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboneskull%2Fxstate-audition/lists"}