Add vitest plugin for testing full workflows without setting up a server

[VaguelySerious]

Superseeds #822. This allows users to add a vitest plugin enabling running of a workflow without a server instance, so you can e2e test a full workflow with given inputs.

Also introduces test helpers for "expect and skip next wait" and "expect and resolve next hook with ".

New docs link

Note this doesn't allow mocking due to how SWC bundles the step/run separately. There's a callout for that and it's already not supported in the existing docs/setup. I added a separate markdown file to the workbench with what Claude thinks is the way forward for that, and my personal take is that it's hard and we should not worry about it right now

[changeset-bot]

🦋 Changeset detected

Latest commit: cc79cd0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 17 packages

Name	Type
@workflow/core	Patch
workflow	Patch
@workflow/vitest	Patch
@workflow/world-local	Patch
@workflow/builders	Patch
@workflow/cli	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/web-shared	Patch
@workflow/world-testing	Patch
@workflow/world-postgres	Patch
@workflow/astro	Patch
@workflow/nest	Patch
@workflow/rollup	Patch
@workflow/sveltekit	Patch
@workflow/vite	Patch
@workflow/nuxt	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
example-nextjs-workflow-turbopack	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
example-nextjs-workflow-webpack	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
example-workflow	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workbench-astro-workflow	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workbench-express-workflow	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workbench-fastify-workflow	Building	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workbench-hono-workflow	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workbench-nitro-workflow	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workbench-nuxt-workflow	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workbench-sveltekit-workflow	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workbench-vite-workflow	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workflow-docs	Ready	Preview, ✅ 2 resolved, Open in v0	Mar 4, 2026 9:17pm
workflow-nest	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm
workflow-swc-playground	Ready	Preview, Comment, Open in v0	Mar 4, 2026 9:17pm

[github-actions]

🧪 E2E Test Results

❌ Some tests failed

Summary

	Passed	Failed	Skipped	Total
✅ ▲ Vercel Production	538	0	67	605
✅ 💻 Local Development	576	0	84	660
✅ 📦 Local Production	576	0	84	660
✅ 🐘 Local Postgres	576	0	84	660
✅ 🪟 Windows	52	0	3	55
❌ 🌍 Community Worlds	117	48	15	180
✅ 📋 Other	138	0	27	165
Total	2573	48	364	2985

❌ Failed Tests

🌍 Community Worlds (48 failed)

turso (48 failed):

• addTenWorkflow
• addTenWorkflow
• wellKnownAgentWorkflow (.well-known/agent)
• should work with react rendering in step
• promiseAllWorkflow
• promiseRaceWorkflow
• promiseAnyWorkflow
• importedStepOnlyWorkflow
• hookWorkflow
• webhookWorkflow
• sleepingWorkflow
• parallelSleepWorkflow
• nullByteWorkflow
• workflowAndStepMetadataWorkflow
• fetchWorkflow
• promiseRaceStressTestWorkflow
• error handling error propagation workflow errors nested function calls preserve message and stack trace
• error handling error propagation workflow errors cross-file imports preserve message and stack trace
• error handling error propagation step errors basic step error preserves message and stack trace
• error handling error propagation step errors cross-file step error preserves message and function names in stack
• error handling retry behavior regular Error retries until success
• error handling retry behavior FatalError fails immediately without retries
• error handling retry behavior RetryableError respects custom retryAfter delay
• error handling retry behavior maxRetries=0 disables retries
• error handling retry behavior workflow completes despite transient 5xx on step_completed
• error handling catchability FatalError can be caught and detected with FatalError.is()
• hookCleanupTestWorkflow - hook token reuse after workflow completion
• concurrent hook token conflict - two workflows cannot use the same hook token simultaneously
• hookDisposeTestWorkflow - hook token reuse after explicit disposal while workflow still running
• stepFunctionPassingWorkflow - step function references can be passed as arguments (without closure vars)
• stepFunctionWithClosureWorkflow - step function with closure variables passed as argument
• closureVariableWorkflow - nested step functions with closure variables
• spawnWorkflowFromStepWorkflow - spawning a child workflow using start() inside a step
• health check (queue-based) - workflow and step endpoints respond to health check messages
• pathsAliasWorkflow - TypeScript path aliases resolve correctly
• Calculator.calculate - static workflow method using static step methods from another class
• AllInOneService.processNumber - static workflow method using sibling static step methods
• ChainableService.processWithThis - static step methods using this to reference the class
• thisSerializationWorkflow - step function invoked with .call() and .apply()
• customSerializationWorkflow - custom class serialization with WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE
• instanceMethodStepWorkflow - instance methods with "use step" directive
• crossContextSerdeWorkflow - classes defined in step code are deserializable in workflow context
• stepFunctionAsStartArgWorkflow - step function reference passed as start() argument
• cancelRun - cancelling a running workflow
• cancelRun via CLI - cancelling a running workflow
• pages router addTenWorkflow via pages router
• pages router promiseAllWorkflow via pages router
• pages router sleepingWorkflow via pages router

Details by Category

✅ ▲ Vercel Production

App	Passed	Failed	Skipped
✅ astro	48	0	7
✅ example	48	0	7
✅ express	48	0	7
✅ fastify	48	0	7
✅ hono	48	0	7
✅ nextjs-turbopack	53	0	2
✅ nextjs-webpack	53	0	2
✅ nitro	48	0	7
✅ nuxt	48	0	7
✅ sveltekit	48	0	7
✅ vite	48	0	7

✅ 💻 Local Development

App	Passed	Failed	Skipped
✅ astro-stable	46	0	9
✅ express-stable	46	0	9
✅ fastify-stable	46	0	9
✅ hono-stable	46	0	9
✅ nextjs-turbopack-canary	52	0	3
✅ nextjs-turbopack-stable	52	0	3
✅ nextjs-webpack-canary	52	0	3
✅ nextjs-webpack-stable	52	0	3
✅ nitro-stable	46	0	9
✅ nuxt-stable	46	0	9
✅ sveltekit-stable	46	0	9
✅ vite-stable	46	0	9

✅ 📦 Local Production

App	Passed	Failed	Skipped
✅ astro-stable	46	0	9
✅ express-stable	46	0	9
✅ fastify-stable	46	0	9
✅ hono-stable	46	0	9
✅ nextjs-turbopack-canary	52	0	3
✅ nextjs-turbopack-stable	52	0	3
✅ nextjs-webpack-canary	52	0	3
✅ nextjs-webpack-stable	52	0	3
✅ nitro-stable	46	0	9
✅ nuxt-stable	46	0	9
✅ sveltekit-stable	46	0	9
✅ vite-stable	46	0	9

✅ 🐘 Local Postgres

App	Passed	Failed	Skipped
✅ astro-stable	46	0	9
✅ express-stable	46	0	9
✅ fastify-stable	46	0	9
✅ hono-stable	46	0	9
✅ nextjs-turbopack-canary	52	0	3
✅ nextjs-turbopack-stable	52	0	3
✅ nextjs-webpack-canary	52	0	3
✅ nextjs-webpack-stable	52	0	3
✅ nitro-stable	46	0	9
✅ nuxt-stable	46	0	9
✅ sveltekit-stable	46	0	9
✅ vite-stable	46	0	9

✅ 🪟 Windows

App	Passed	Failed	Skipped
✅ nextjs-turbopack	52	0	3

❌ 🌍 Community Worlds

App	Passed	Failed	Skipped
✅ mongodb-dev	3	0	2
✅ mongodb	52	0	3
✅ redis-dev	3	0	2
✅ redis	52	0	3
✅ turso-dev	3	0	2
❌ turso	4	48	3

✅ 📋 Other

App	Passed	Failed	Skipped
✅ e2e-local-dev-nest-stable	46	0	9
✅ e2e-local-postgres-nest-stable	46	0	9
✅ e2e-local-prod-nest-stable	46	0	9

---

📋 View full workflow run

[pranaygp]

is this correct, or does it need to be "index"?

[pranaygp]

nit: I don't think we actually do anything with these rn? I think claude hallucinated this front matter.

Would be nice to actually use them in the future though. Maybe a geistdocs thing

[pranaygp]

I think the server example wouldn't actually do this since it wouldn't reuse the http layer of the actual app the user is going to productionize against no? the nitro sidecar is in itself a separate server

I still see the value of it if people want to test against an actual server and then they can customize the nitro server to match their setup?

It's maybe at least worth noting that, this i an example with a nitro server for a full simulated test and is meant to be a starting point for users to further customize for their own testing needs

[pranaygp]

Suggested change

	2. **Integration testing** - Test entire workflows in-process using the `workflow()` Vitest plugin. Required for workflows that use [hooks](/docs/foundations/hooks), webhooks, [`sleep()`](/docs/api-reference/workflow/sleep), or retries.
	2. **Integration testing** - Test entire workflows in-process using the `workflow()` Vitest plugin. Required when you want to test workflow specific code paths, like those using [hooks](/docs/foundations/hooks), webhooks, [`sleep()`](/docs/api-reference/workflow/sleep), retries, etc.

(metadata, locks, etc. are all relevant here but we dont' need to list everything)

[pranaygp]

I don't understand this? why would mocks not work in the vitest runtime? is this not a deal breaker?

[VaguelySerious]

It doesn't work for first-party code, but it might work for third-party dependencies. We should extend the vitest workbench app to add an import for an npm package and then mock it out, and then test whether the mock works. If yes, we should update this Callout to be more specific. If not, let's document that case too in the markdown file inside the vitest workbench.

[pranaygp]

question: do we clean up local filesystem across individual tests? or across test runs? etc.

in other words, what's the test isolation story?

for example, a hook token won't be reusable if you have a test run that didn't complete in the past right (remember that in local world, you could Ctrl+C a run midway, and it won't resume automatically in future restarts)

maybe we should clean up the local world data directory on test start/(i.e. before all)? That way the runs are still observable after a test run is complete, but each run is isolated

[pranaygp]

(if you've already implemented this, ignore me. I'm just reading the docs rn - not the code yet).
consider any doc updates based on my questions as you see fit :)

[pranaygp]

Suggested change

	const result = await run.returnValue; // [!code highlight]
	// waiting for the return value will block till the run completes (fails or succeeds)
	const result = await run.returnValue; // [!code highlight]
	const status = await run.status;
	expect(status).toEqual("completed");

(suggestion written by hand - pls validate types/typos when incorporating)

[pranaygp]

let's cross link to run.returnValue docs in API reference? (so people/agents can figure out that it will block till ready, and throw if the workflow fails, etc.)

[pranaygp]

comment here that calling wakeUp() without correlation IDs will resume all/any active sleeps at this time

[pranaygp]

question: does waitForSleep return immediately if there are previous sleeps already active?

psudeocode:

startRun that triggers 2 sleeps in parallel
waitFor Sleep().. (how many sleeps will it return? 1 or both?)
wakeUp(1 of the sleeps)
waitForSleep() (will this immediately return the other sleep pending?
wakeUp(the other sleep)
waitForSleep() (will this block indefinitely now since all sleeps are resolved?

[pranaygp]

we have resumeWebhook actually and we should use that. I think this is the only valid usecase for resumeWebhook.

1. it's already type safe
2. it will correctly only resume webhooks (and not normal hook)

[pranaygp]

can we please add an API reference section for the @workflow/vitest package that includes API reference sections for waitForSleep and waitForHook

at least so that the TSDoc generation works and those pages have something populated

[pranaygp]

good change

[TooTallNate]

setup-file.ts calls setupWorkflowTests() but never calls teardownWorkflowTests(). The manual setup example in the docs shows afterAll(() => teardownWorkflowTests()), but the automatic path skips this. This could leak resources or let state bleed between test files in a multi-file suite.

Consider adding teardown registration here:

import { setupWorkflowTests, teardownWorkflowTests } from "./index.js";
import { afterAll } from "vitest";

await setupWorkflowTests();

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

[TooTallNate]

The data directory at join(outDir, "data") persists across test runs. Events and hooks from previous runs remain on disk, which could cause waitForSleep / waitForHook to match stale events from a prior run if the same runId prefix collides. Consider clearing or recreating the data directory at the start of setupWorkflowTests (or in buildWorkflowTests) to guarantee test isolation.

[TooTallNate]

The plugin returns Vite Plugin[] and the test helpers use types from @workflow/core, but vite and vitest are not listed as peerDependencies. Users need compatible versions for the plugin to work. Consider adding:

"peerDependencies": {
  "vite": ">=6.0.0",
  "vitest": ">=3.0.0"
}

(with appropriate version ranges for your supported matrix)

[TooTallNate]

This README appears stale — it references a Nitro server-based approach with vitest.setup.ts (global setup) and a nitro.config.ts-centric project structure, but the workbench actually uses the new in-process @workflow/vitest plugin. The project structure section lists files that do not exist (e.g. vitest.setup.ts) and omits real ones (workflows/hooks.ts, workflows/sleeping.ts, workflows/webhook.ts). Worth updating to match the actual setup.

[TooTallNate]

This assumes any queue name that does not start with __wkf_step_ must be __wkf_workflow_. If the queue name has a different prefix entirely, it will still look up __wkf_workflow_ in the direct handlers map and likely get undefined, which happens to fall through to the HTTP path — so it works by accident. But the intent would be clearer with explicit checks:

const prefix = queueName.startsWith("__wkf_step_")
  ? "__wkf_step_"
  : queueName.startsWith("__wkf_workflow_")
    ? "__wkf_workflow_"
    : undefined;
const directHandler = prefix ? directHandlers.get(prefix) : undefined;

[TooTallNate]

Review Summary

Great feature — running full workflow integration tests in-process without a server is a significant DX improvement. The core approach of registering direct handlers on the local world queue is elegant and minimal.

What looks good

• Clean architecture: globalSetup builds bundles, setupFile wires up in-process handlers via registerHandler()
• waitForSleep() and waitForHook() test helpers are well-designed with sensible polling + timeout defaults
• Docs rewrite is excellent — leading with the simpler in-process approach and moving server-based to its own page
• Honest callout about vi.mock() limitations, with thorough internal analysis in MOCKING.md
• CI properly isolates the vitest workbench tests into their own job
• Good test coverage in the workbench (simple, sleeping, hooks, webhooks)

Items to address

1. Missing teardown in setup-file.ts — resources/state may leak between test files
2. Prefix detection in queue.ts — falls through to __wkf_workflow_ for unknown queue names (works by accident)
3. Stale data directory — .workflow-vitest/data persists between runs, risking event collisions
4. Missing peer dependencies — vite and vitest should be peer deps in @workflow/vitest
5. Stale workbench README — references Nitro server approach and files that no longer exist

Minor / non-blocking

• resolveBaseUrl moved inside the retry loop for the HTTP path (was previously hoisted)
• Incidental formatting changes in .changeset/config.json
• undici 7.16.0 -> 7.22.0 bump in lockfile (harmless but unrelated)

Overall this is close to ready. The teardown and data isolation issues are the most important to address before merge.