@workflow/vitest

The @workflow/vitest package provides a Vitest plugin and test helpers for running full workflow integration tests in-process, no server required.

Installation

npm i -D @workflow/vitest

Plugin

workflow()

Returns a Vite plugin array that handles SWC transforms, bundle building, and in-process handler registration automatically.

import { defineConfig } from "vitest/config";
import { workflow } from "@workflow/vitest";

export default defineConfig({
  plugins: [workflow()],
});

Pass a WorkflowTestOptions object when your project uses a non-standard layout, for example, a monorepo where workflows/ does not live at the Vitest config's directory, or when the default .workflow-data / .workflow-vitest output locations need to move. The plugin forwards these paths to buildWorkflowTests() and setupWorkflowTests() through Vitest's per-project provided context, so each Vitest workspace project stays isolated.

import { defineConfig } from "vitest/config";
import { workflow } from "@workflow/vitest";

export default defineConfig({
  plugins: [
    workflow({
      cwd: "./apps/api",
      rootDir: "./apps/api/test-artifacts",
    }),
  ],
});

Parameters:

Returns: Plugin[]

Setup functions

buildWorkflowTests()

Builds workflow and step bundles to disk. Called automatically by the workflow() plugin in globalSetup. Use directly only for manual setup.

import { buildWorkflowTests } from "@workflow/vitest";

export async function setup() {
  await buildWorkflowTests();
}

Parameters:

setupWorkflowTests()

Sets up an in-process workflow runtime in each test worker. Imports pre-built bundles, creates a Local World instance with direct handlers, and sets it as the global world. Clears all workflow data on each invocation for full test isolation.

Called automatically by the workflow() plugin in setupFiles. Use directly only for manual setup.

import { beforeAll, afterAll } from "vitest";
import { setupWorkflowTests, teardownWorkflowTests } from "@workflow/vitest";

beforeAll(async () => {
  await setupWorkflowTests();
});

afterAll(async () => {
  await teardownWorkflowTests();
});

Parameters:

teardownWorkflowTests()

Tears down the workflow test world. Clears the global world and closes the Local World instance. Called automatically by the workflow() plugin.

Returns: Promise<void>

WorkflowTestOptions

Workflow references

The test build writes the same manifest.json the other Workflow builders write into outDir. These helpers read it, so a test can name a workflow instead of hand-writing the generated workflow//... id. Importing the workflow function is still preferable when a test can do it, because it keeps the argument and return types.

getWorkflowRef()

Looks up one workflow in the test build and returns it in the shape start() accepts.

import { getWorkflowRef } from "@workflow/vitest";
import { start } from "workflow/api";

const run = await start(getWorkflowRef("approvalWorkflow"), ["doc-1"]);

query is an exported workflow name, or a file-qualified name when the same name appears in more than one file: getWorkflowRef("workflows/approval.ts#approvalWorkflow"). The file part also matches by path suffix, so "approval.ts#approvalWorkflow" resolves the same entry.

Parameters:

Returns: WorkflowRef.

Throws when the manifest is missing (the plugin or buildWorkflowTests() has not run), when nothing matches, or when the name is ambiguous. The message lists the workflows the build contains.

listWorkflowRefs()

Returns every workflow in the test build, sorted by file and then name.

import { listWorkflowRefs } from "@workflow/vitest";

const names = listWorkflowRefs().map((ref) => ref.name);

Returns: WorkflowRef[].

WorkflowRef

Test helpers

waitForSleep()

Polls the event log until the workflow has a pending sleep() call, one with a wait_created event but no corresponding wait_completed event. Returns the correlation ID of the pending sleep, which can be passed to wakeUp() to target a specific sleep.

import { waitForSleep } from "@workflow/vitest";
import { start, getRun } from "workflow/api";

const run = await start(myWorkflow, []);
const sleepId = await waitForSleep(run);
await getRun(run.runId).wakeUp({ correlationIds: [sleepId] });

Parameters:

Returns: Promise<string>, the correlation ID of the first pending sleep. Pass this to wakeUp({ correlationIds: [id] }) to target a specific sleep.

Behavior with multiple sleeps

• Sequential sleeps: waitForSleep() returns each sleep as the workflow reaches it. After waking one, call waitForSleep() again for the next.
• Parallel sleeps: waitForSleep() returns whichever pending sleep is found first. After waking it, call waitForSleep() again to get the next one.

waitForHook()

Polls the hook list and event log until a hook matching the optional token filter exists that hasn't been received yet. Returns the matching hook object.

import { waitForHook } from "@workflow/vitest";
import { start, resumeHook } from "workflow/api";

const run = await start(myWorkflow, ["doc-1"]);
const hook = await waitForHook(run, { token: "approval:doc-1" });
await resumeHook(hook.token, { approved: true });

Parameters:

Returns: Promise<Hook>, the first pending hook matching the filter. The hook object includes token, hookId, and runId.

WaitOptions

Both waitForSleep() and waitForHook() accept options for controlling polling behavior: