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: ff832ee

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

This PR includes changesets to release 17 packages

Name	Type
@workflow/world-local	Patch
workflow	Patch
@workflow/vitest	Patch
@workflow/cli	Patch
@workflow/core	Patch
@workflow/world-postgres	Patch
@workflow/world-testing	Patch
@workflow/builders	Patch
@workflow/next	Patch
@workflow/nitro	Patch
@workflow/web-shared	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 5, 2026 11:58pm
example-nextjs-workflow-webpack	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
example-workflow	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workbench-astro-workflow	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workbench-express-workflow	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workbench-fastify-workflow	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workbench-hono-workflow	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workbench-nitro-workflow	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workbench-nuxt-workflow	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workbench-sveltekit-workflow	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workbench-vite-workflow	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workflow-docs	Ready	Preview, ✅ 2 resolved, Open in v0	Mar 5, 2026 11:58pm
workflow-nest	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm
workflow-swc-playground	Ready	Preview, Comment, Open in v0	Mar 5, 2026 11:58pm

[github-actions]

🧪 E2E Test Results

❌ Some tests failed

Summary

	Passed	Failed	Skipped	Total
✅ ▲ Vercel Production	549	0	67	616
✅ 💻 Local Development	588	0	84	672
✅ 📦 Local Production	588	0	84	672
❌ 🐘 Local Postgres	587	1	84	672
✅ 🪟 Windows	53	0	3	56
❌ 🌍 Community Worlds	116	52	15	183
✅ 📋 Other	141	0	27	168
Total	2622	53	364	3039

❌ Failed Tests

🐘 Local Postgres (1 failed)

fastify-stable (1 failed):

• webhookWorkflow

🌍 Community Worlds (52 failed)

mongodb (2 failed):

• hookWorkflow is not resumable via public webhook endpoint
• webhookWorkflow

redis (1 failed):

• hookWorkflow is not resumable via public webhook endpoint

turso (49 failed):

• addTenWorkflow
• addTenWorkflow
• wellKnownAgentWorkflow (.well-known/agent)
• should work with react rendering in step
• promiseAllWorkflow
• promiseRaceWorkflow
• promiseAnyWorkflow
• importedStepOnlyWorkflow
• hookWorkflow
• hookWorkflow is not resumable via public webhook endpoint
• 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	49	0	7
✅ example	49	0	7
✅ express	49	0	7
✅ fastify	49	0	7
✅ hono	49	0	7
✅ nextjs-turbopack	54	0	2
✅ nextjs-webpack	54	0	2
✅ nitro	49	0	7
✅ nuxt	49	0	7
✅ sveltekit	49	0	7
✅ vite	49	0	7

✅ 💻 Local Development

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

✅ 📦 Local Production

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

❌ 🐘 Local Postgres

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

✅ 🪟 Windows

App	Passed	Failed	Skipped
✅ nextjs-turbopack	53	0	3

❌ 🌍 Community Worlds

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

✅ 📋 Other

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

---

📋 View full workflow run

---

❌ Some E2E test jobs failed:

• Vercel Prod: success
• Local Dev: success
• Local Prod: success
• Local Postgres: failure
• Windows: success

Check the workflow run for details.

[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.)

[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]

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.

[TooTallNate]

Review Summary (follow-up)

All previous feedback from both my review and @pranaygp's review has been addressed. The updates are well done. Here's the status:

Previous Feedback — All Resolved

Item	Status
Missing teardown in setup-file.ts	Fixed — afterAll(() => teardownWorkflowTests()) added
Stale data directory / test isolation	Fixed — world.clear() on setup + per-worker VITEST_POOL_ID dirs
Missing peer dependencies	Fixed — vite >=6.0.0 and vitest >=3.0.0 added
Stale workbench README	Fixed — fully rewritten
Queue prefix falls through for unknown names	Fixed — explicit if/else if/else throw
Missing changesets (pranaygp)	Fixed — new changesets for @workflow/vitest and @workflow/world-local
Separate @workflow/vitest package (pranaygp)	Fixed — no longer bundled in workflow/vitest
meta.json pages (pranaygp)	Fixed — ["index", "server-based"]
Hallucinated front matter (pranaygp)	Fixed — removed
Server-based page framing (pranaygp)	Fixed — noted as starting point
vi.mock() callout (pranaygp)	Fixed — clear warning callout added
Test isolation docs (pranaygp)	Fixed — documented
run.status + returnValue blocking (pranaygp)	Fixed — example updated
Cross-link to run.returnValue docs (pranaygp)	Fixed
wakeUp() without correlationIds comment (pranaygp)	Fixed
waitForSleep multi-sleep behavior (pranaygp)	Fixed — dedicated callout
Use resumeWebhook for webhooks (pranaygp)	Fixed
API reference for @workflow/vitest (pranaygp)	Fixed — full page at docs/api-reference/vitest/

CI Failures to Fix

Two CI jobs are failing on the latest commit:

1. Vitest Plugin Tests — webhook test fails

Error: `createWebhook()` does not accept a `token` option. Webhook tokens are always
randomly generated. Use `createHook()` with `resumeHook()` for deterministic token patterns.

The webhookWorkflow in workbench/vitest/workflows/webhook.ts passes a token option to createWebhook(), but it looks like createWebhook now rejects custom tokens. The test and workflow need to be updated to match the current createWebhook API — either use a randomly generated token (and discover it via waitForHook without a token filter, using the hook object's token to call resumeWebhook), or switch to createHook if deterministic tokens are needed. The docs webhook example (docs/content/docs/testing/index.mdx:258) also uses token in createWebhook and would need the same fix.

2. Docs Code Samples — type-check failures in api-reference/vitest/index.mdx

Three code samples fail type-checking:

• Line 15: defineConfig not imported (missing import { defineConfig } from "vitest/config")
• Line 32: buildWorkflowTests not imported (missing import from @workflow/vitest)
• Line 52: beforeAll/afterAll not imported (missing import from vitest)

These are the shorter code snippets in the API reference page that don't include their imports. Either add the imports or use @skip-typecheck comments like the test helper examples already do.

Minor Nits (non-blocking)

• Both vite and vitest peer deps are marked optional. Consider making vitest non-optional since the primary use case requires it.
• buildTarget: 'next' in VitestBuilder (packages/vitest/src/index.ts:22) — a brief comment explaining why 'next' is the right target for vitest builds would help future readers.