workflow 4.2.0-beta.64 → 4.2.0-beta.66

package/docs/ai/index.mdx

@@ -151,7 +151,7 @@ import { z } from "zod";
 export const tools = {
   searchFlights: tool({
     description: "Search for flights",
-    inputSchema: z.object({ query: z.string() }),
+    inputSchema: z.object({ from: z.string(), to: z.string(), date: z.string() }),
     execute: searchFlights,
   }),
 };

package/docs/api-reference/index.mdx

@@ -20,4 +20,7 @@ All the functions and primitives that come with Workflow DevKit by package.
     <Card title="@workflow/ai" href="/docs/api-reference/workflow-ai">
         Helpers for integrating AI SDK for building AI-powered workflows.
     </Card>
+    <Card title="@workflow/vitest" href="/docs/api-reference/vitest">
+        Vitest plugin and test helpers for integration testing workflows in-process.
+    </Card>
 </Cards>

package/docs/api-reference/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "API Reference",
-  "pages": ["...", "workflow-ai"]
+  "pages": ["...", "workflow-ai", "vitest"]
 }

package/docs/api-reference/vitest/index.mdx

@@ -0,0 +1,150 @@
+---
+title: "@workflow/vitest"
+description: Vitest plugin and test helpers for integration testing workflows in-process.
+---
+
+The `@workflow/vitest` package provides a Vitest plugin and test helpers for running full workflow integration tests in-process — no server required.
+
+## Plugin
+
+### `workflow()`
+
+Returns a Vite plugin array that handles SWC transforms, bundle building, and in-process handler registration automatically.
+
+{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
+
+```typescript
+import { defineConfig } from "vitest/config";
+import { workflow } from "@workflow/vitest"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [workflow()], // [!code highlight]
+});
+```
+
+**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](/docs/testing#manual-setup).
+
+{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
+
+```typescript
+import { buildWorkflowTests } from "@workflow/vitest";
+
+export async function setup() {
+  await buildWorkflowTests();
+}
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options?` | `WorkflowTestOptions` | Optional configuration |
+
+### `setupWorkflowTests()`
+
+Sets up an in-process workflow runtime in each test worker. Imports pre-built bundles, creates a [Local World](/docs/worlds/local) 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](/docs/testing#manual-setup).
+
+{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
+
+```typescript
+import { beforeAll, afterAll } from "vitest";
+import { setupWorkflowTests, teardownWorkflowTests } from "@workflow/vitest";
+
+beforeAll(async () => {
+  await setupWorkflowTests();
+});
+
+afterAll(async () => {
+  await teardownWorkflowTests();
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options?` | `WorkflowTestOptions` | Optional configuration |
+
+### `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`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `cwd` | `string` | `process.cwd()` | The working directory of the project (where `workflows/` lives) |
+
+## 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()`](/docs/api-reference/workflow-api/get-run) to target a specific sleep.
+
+{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
+
+```typescript
+import { waitForSleep } from "@workflow/vitest"; // [!code highlight]
+import { start, getRun } from "workflow/api";
+
+const run = await start(myWorkflow, []);
+const sleepId = await waitForSleep(run); // [!code highlight]
+await getRun(run.runId).wakeUp({ correlationIds: [sleepId] }); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `run` | `Run<any>` | The workflow run to monitor |
+| `options?` | `WaitOptions` | Polling and timeout configuration |
+
+**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.
+
+{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
+
+```typescript
+import { waitForHook } from "@workflow/vitest"; // [!code highlight]
+import { start, resumeHook } from "workflow/api";
+
+const run = await start(myWorkflow, ["doc-1"]);
+const hook = await waitForHook(run, { token: "approval:doc-1" }); // [!code highlight]
+await resumeHook(hook.token, { approved: true }); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `run` | `Run<any>` | The workflow run to monitor |
+| `options?` | `WaitOptions & { token?: string }` | Polling, timeout, and optional token filter |
+
+**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:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `timeout` | `number` | `30000` | Maximum time to wait in milliseconds |
+| `pollInterval` | `number` | `100` | Polling interval in milliseconds |

package/docs/api-reference/workflow/get-writable.mdx

@@ -209,7 +209,7 @@ Here's a more complex example showing how you might stream AI chat responses:
 import { getWritable } from "workflow";
 import { generateId, streamText, type UIMessageChunk } from "ai";
 
-export async function chat(messages: UIMessage[]) {
+export async function chat(messages: ModelMessage[]) {
   "use workflow";
 
   // Get typed writable stream for UI message chunks
@@ -223,7 +223,7 @@ export async function chat(messages: UIMessage[]) {
   // Process messages in steps
   for (let i = 0; i < MAX_STEPS; i++) {
     const result = await streamTextStep(currentMessages, writable);
-    currentMessages.push(result.messages);
+    currentMessages.push(...result.messages);
 
     if (result.finishReason !== "tool-calls") {
       break;
@@ -252,7 +252,7 @@ async function startStream(writable: WritableStream<UIMessageChunk>) {
 }
 
 async function streamTextStep(
-  messages: UIMessage[],
+  messages: ModelMessage[],
   writable: WritableStream<UIMessageChunk>
 ) {
   "use step";
@@ -261,9 +261,8 @@ async function streamTextStep(
 
   // Call streamText from the AI SDK
   const result = streamText({
-    model: "gpt-4",
+    model: myModel,
     messages,
-    /* other options */
   });
 
   // Pipe the AI stream into the writable stream

package/docs/api-reference/workflow-api/get-hook-by-token.mdx

@@ -89,9 +89,10 @@ export async function POST(request: Request) {
 
   try {
     const hook = await getHookByToken(token); // [!code highlight]
+    const metadata = hook.metadata as { allowedUserId?: string } | undefined;
 
     // Validate that the hook metadata matches the user
-    if (hook.metadata?.allowedUserId !== userId) {
+    if (metadata?.allowedUserId !== userId) {
       return Response.json(
         { error: "Unauthorized to resume this hook" },
         { status: 403 }

package/docs/errors/hook-conflict.mdx

@@ -85,7 +85,7 @@ export async function processPayment(orderId: string) {
     const payment = await hook; // [!code highlight]
     return { success: true, payment };
   } catch (error) {
-    if (error instanceof WorkflowRuntimeError && error.slug === "hook-conflict") { // [!code highlight]
+    if (error instanceof WorkflowRuntimeError && error.message.includes("hook-conflict")) { // [!code highlight]
       // Another workflow is already processing this order
       return { success: false, reason: "duplicate-processing" };
     }

package/docs/foundations/streaming.mdx

@@ -120,7 +120,7 @@ import { streamProcessingWorkflow } from "./workflows/streaming";
 export async function POST(request: Request) {
   // Streams can be passed as workflow arguments
   const run = await start(streamProcessingWorkflow, [request.body]); // [!code highlight]
-  await run.result();
+  await run.returnValue;
 
   return Response.json({ status: "complete" });
 }

package/docs/foundations/workflows-and-steps.mdx

@@ -136,7 +136,7 @@ import { sleep, createWebhook } from "workflow";
 export async function documentReviewProcess(userId: string) {
   "use workflow";
 
-  await sleep("1 month"); // Sleep will suspend without consuming any resources [!code highlight]
+  await sleep("30d"); // Sleep will suspend without consuming any resources [!code highlight]
 
   // Create a webhook for external workflow resumption
   const webhook = createWebhook();

package/docs/testing/index.mdx

@@ -1,25 +1,14 @@
 ---
 title: Testing
-description: Unit test individual steps and integration test entire workflows using Vitest and the Vite plugin.
-type: conceptual
-summary: Learn how to unit test steps and integration test workflows using Vitest.
-prerequisites:
-  - /docs/foundations/workflows-and-steps
-  - /docs/getting-started/vite
-related:
-  - /docs/foundations/hooks
-  - /docs/api-reference/workflow-api/start
-  - /docs/api-reference/workflow-api/resume-hook
-  - /docs/api-reference/workflow-api/get-run
-  - /docs/observability
+description: Unit test individual steps and integration test entire workflows using Vitest.
 ---
 
-Testing is a critical part of building reliable workflows. Because steps are just functions annotated with directives, they can be unit tested like any other JavaScript function. Workflow DevKit also provides a [Vite plugin](/docs/getting-started/vite) that integrates with [Vitest](https://vitest.dev), enabling full integration tests against a real workflow runtime.
+Testing is a critical part of building reliable workflows. Because steps are just functions annotated with directives, they can be unit tested like any other JavaScript function. Workflow DevKit also provides a Vitest plugin that runs full workflows in-process — no running server required.
 
 This guide covers two approaches:
 
 1. **Unit testing** - Test individual steps as plain functions, without the workflow runtime.
-2. **Integration testing** - Test entire workflows against a real workflow setup using the Vite 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.
 
 ## Unit Testing Steps
 
@@ -88,125 +77,71 @@ describe("sendWelcomeEmail step", () => {
 This approach is ideal for verifying the business logic inside individual steps in isolation.
 
 <Callout type="info">
-Unit testing works well for individual steps. A simple workflow that only calls steps can also be unit tested this way, since `"use workflow"` is similarly a no-op without the compiler. However, any workflow that uses runtime features like [`sleep()`](/docs/api-reference/workflow/sleep), [hooks](/docs/foundations/hooks), or [webhooks](/docs/foundations/hooks#understanding-webhooks) cannot be unit tested directly because those APIs require the workflow runtime. Use [integration testing](#integration-testing-with-the-vite-plugin) for testing entire workflows, especially those that depend on workflow-only features.
+Unit testing works well for individual steps. A simple workflow that only calls steps can also be unit tested this way, since `"use workflow"` is similarly a no-op without the compiler. However, any workflow that uses runtime features like [`sleep()`](/docs/api-reference/workflow/sleep), [hooks](/docs/foundations/hooks), or [webhooks](/docs/foundations/hooks#understanding-webhooks) cannot be unit tested directly because those APIs require the workflow runtime. Use [integration testing](#integration-testing-with-the-vitest-plugin) for testing entire workflows, especially those that depend on workflow-only features.
 </Callout>
 
-## Integration Testing with the Vite Plugin
+## Integration Testing with the Vitest Plugin
 
-For workflows that rely on runtime features like [hooks](/docs/foundations/hooks), [webhooks](/docs/foundations/hooks#understanding-webhooks), [`sleep()`](/docs/api-reference/workflow/sleep), or error retries, you need to test against a real workflow setup. The `workflow/vite` plugin integrates directly with Vitest, compiling your `"use workflow"` and `"use step"` directives so the full workflow runtime is active during tests.
+For workflows that rely on runtime features like [hooks](/docs/foundations/hooks), [webhooks](/docs/foundations/hooks#understanding-webhooks), [`sleep()`](/docs/api-reference/workflow/sleep), or error retries, you need to test against a real workflow setup. The `@workflow/vitest` plugin handles everything automatically — it compiles your workflow directives, builds the runtime bundles, and executes workflows entirely in-process. No server required.
+
+<Callout type="warn">
+Inside integration tests, which run the full workflow runtime, `vi.mock()` and related calls do not work — neither for your own modules nor for third-party npm packages. All step dependencies are inlined into the compiled bundle by esbuild, bypassing Vitest's module system entirely. To test steps with mocked dependencies, use [unit tests](#unit-testing-steps) instead. Consider dependency injection or environment variable-based conditional logic for controlling behavior in integration tests.
+</Callout>
 
 ### Vitest Configuration
 
-Create a separate Vitest config for integration tests that includes the `workflow()` plugin and a `globalSetup` script:
+Create a separate Vitest config for integration tests that includes the `workflow()` plugin:
 
 ```typescript title="vitest.integration.config.ts" lineNumbers
 import { defineConfig } from "vitest/config";
-import { workflow } from "workflow/vite"; // [!code highlight]
+import { workflow } from "@workflow/vitest"; // [!code highlight]
 
 export default defineConfig({
   plugins: [workflow()], // [!code highlight]
   test: {
     include: ["**/*.integration.test.ts"],
     testTimeout: 60_000, // Workflows may take longer than default timeout
-    globalSetup: "./vitest.integration.setup.ts", // [!code highlight]
   },
 });
 ```
 
+That's it. The plugin automatically:
+
+1. Transforms `"use workflow"` and `"use step"` directives via SWC
+2. Builds workflow and step bundles before tests run
+3. Sets up an in-process workflow runtime using a fresh [Local World](/docs/worlds/local) instance in each test worker — all workflow data is cleared automatically between test files for full isolation
+
 <Callout type="info">
 Use a separate Vitest configuration and a distinct file naming convention (e.g. `*.integration.test.ts`) to keep unit tests and integration tests separate. Unit tests run with a standard Vitest config without the workflow plugin, while integration tests use the config above.
 </Callout>
 
-### Global Setup Script
-
-Integration tests need a running server to execute workflow steps. The `globalSetup` script starts a [Nitro](https://v3.nitro.build) server as a sidecar process before tests run, and tears it down afterwards:
-
-```typescript title="vitest.integration.setup.ts" lineNumbers
-import { spawn } from "node:child_process";
-import { setTimeout as delay } from "node:timers/promises";
-import type { ChildProcess } from "node:child_process";
+### Writing Integration Tests
 
-let server: ChildProcess | null = null;
-const PORT = "4000";
+Use [`start()`](/docs/api-reference/workflow-api/start) to trigger a workflow and [`run.returnValue`](/docs/api-reference/workflow-api/start#returnvalue) to get the result. `returnValue` is a promise that blocks until the workflow completes (or throws if it fails):
 
-export async function setup() { // [!code highlight]
-  console.log("Starting server for workflow execution...");
+```typescript title="workflows/calculate.integration.test.ts" lineNumbers
+import { describe, it, expect } from "vitest";
+import { start } from "workflow/api"; // [!code highlight]
+import { calculateWorkflow } from "./calculate";
 
-  server = spawn("npx", ["nitro", "dev", "--port", PORT], {
-    stdio: "pipe",
-    detached: false,
-    env: process.env,
-  });
+describe("calculateWorkflow", () => {
+  it("should compute the correct result", async () => {
+    const run = await start(calculateWorkflow, [2, 7]); // [!code highlight]
 
-  // Wait for the server to be ready
-  const ready = await new Promise<boolean>((resolve) => {
-    const timeout = setTimeout(() => resolve(false), 15_000);
-
-    server?.stdout?.on("data", (data) => {
-      const output = data.toString();
-      console.log("[server]", output);
-      if (output.includes("listening") || output.includes("ready")) {
-        clearTimeout(timeout);
-        resolve(true);
-      }
-    });
+    expect(run.runId).toMatch(/^wrun_/);
 
-    server?.stderr?.on("data", (data) => {
-      console.error("[server]", data.toString());
+    // Blocks until the workflow completes or fails
+    const result = await run.returnValue; // [!code highlight]
+    expect(result).toEqual({
+      sum: 9,
+      product: 14,
+      combined: 23,
     });
 
-    server?.on("error", (error) => {
-      console.error("Failed to start server:", error);
-      clearTimeout(timeout);
-      resolve(false);
-    });
+    const status = await run.status; // [!code highlight]
+    expect(status).toEqual("completed");
   });
-
-  if (!ready) {
-    throw new Error("Server failed to start within 15 seconds");
-  }
-
-  await delay(2_000); // Allow full initialization
-
-  // Point the workflow runtime at the local server
-  process.env.WORKFLOW_LOCAL_BASE_URL = `http://localhost:${PORT}`; // [!code highlight]
-  process.env.WORKFLOW_LOCAL_DATA_DIR = "./.workflow-data"; // [!code highlight]
-
-  console.log("Server ready for workflow execution");
-}
-
-export async function teardown() { // [!code highlight]
-  if (server) {
-    console.log("Stopping server...");
-    server.kill("SIGTERM");
-    await delay(1_000);
-    if (!server.killed) {
-      server.kill("SIGKILL");
-    }
-  }
-}
-```
-
-The setup script sets two environment variables that the workflow runtime reads:
-
-- `WORKFLOW_LOCAL_BASE_URL` tells the runtime where to send step execution requests
-- `WORKFLOW_LOCAL_DATA_DIR` tells the runtime where to persist workflow state locally
-
-<Callout type="info">
-You can use any server framework that supports the workflow runtime. The example above uses [Nitro](https://v3.nitro.build), but you could also use a [Next.js](https://nextjs.org), [Hono](https://hono.dev), or any other supported server.
-</Callout>
-
-### Running Integration Tests
-
-Add a script to your `package.json`:
-
-```json title="package.json"
-{
-  "scripts": {
-    "test": "vitest",
-    "test:integration": "vitest --config vitest.integration.config.ts"
-  }
-}
+});
 ```
 
 ### Testing Hooks and Waits
@@ -250,29 +185,32 @@ async function publishDocument(doc: { id: string; content: string }) {
 }
 ```
 
-You can write an integration test that starts the workflow, resumes the hook, and uses [`wakeUp()`](/docs/api-reference/workflow-api/get-run) to skip the sleep — so your tests don't have to wait for the full duration:
+You can write an integration test that starts the workflow, waits for the hook and sleep to be reached, then resumes them programmatically:
 
 ```typescript title="workflows/approval.integration.test.ts" lineNumbers
 import { describe, it, expect } from "vitest";
-import { setTimeout as delay } from "node:timers/promises";
 import { start, getRun, resumeHook } from "workflow/api"; // [!code highlight]
+import { waitForHook, waitForSleep } from "@workflow/vitest"; // [!code highlight]
 import { approvalWorkflow } from "./approval";
 
 describe("approvalWorkflow", () => {
   it("should publish when approved", async () => {
     const run = await start(approvalWorkflow, ["doc-123"]); // [!code highlight]
 
-    // Resume the hook programmatically, simulating an external approval
+    // Wait for the hook to be created, then resume it
+    await waitForHook(run, { token: "approval:doc-123" }); // [!code highlight]
     await resumeHook("approval:doc-123", { // [!code highlight]
       approved: true, // [!code highlight]
       reviewer: "alice", // [!code highlight]
     }); // [!code highlight]
 
-    // Wait for the workflow to replay and reach the sleep() call
-    await delay(5_000); // [!code highlight]
+    // Wait for the first pending sleep to be reached.
+    // waitForSleep() returns the sleep's correlation ID, which can be
+    // passed to wakeUp() later to target a specific sleep in the workflow.
+    const sleepId = await waitForSleep(run); // [!code highlight]
 
-    // Skip the 24-hour sleep so the test completes immediately
-    await getRun(run.runId).wakeUp(); // [!code highlight]
+    // Calling wakeUp() without correlationIds would resume all active sleeps
+    await getRun(run.runId).wakeUp({ correlationIds: [sleepId] }); // [!code highlight]
 
     const result = await run.returnValue;
     expect(result).toEqual({
@@ -284,6 +222,7 @@ describe("approvalWorkflow", () => {
   it("should reject when not approved", async () => {
     const run = await start(approvalWorkflow, ["doc-456"]);
 
+    await waitForHook(run, { token: "approval:doc-456" });
     await resumeHook("approval:doc-456", {
       approved: false,
       reviewer: "bob",
@@ -300,12 +239,124 @@ describe("approvalWorkflow", () => {
 ```
 
 <Callout type="info">
-[`start()`](/docs/api-reference/workflow-api/start), [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook), and [`getRun().wakeUp()`](/docs/api-reference/workflow-api/get-run) are the key API functions for integration testing. Use `start()` to trigger a workflow, `resumeHook()` to simulate external events, and `wakeUp()` to skip `sleep()` calls so tests run instantly. See the [API Reference](/docs/api-reference/workflow-api) for the full list of available functions.
+[`start()`](/docs/api-reference/workflow-api/start), [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook), and [`getRun().wakeUp()`](/docs/api-reference/workflow-api/get-run) are the key API functions for integration testing. Use `start()` to trigger a workflow, `resumeHook()` to simulate external events, and `wakeUp()` to skip `sleep()` calls so tests run instantly. [`waitForSleep()`](/docs/api-reference/vitest#waitforsleep) and [`waitForHook()`](/docs/api-reference/vitest#waitforhook) from `@workflow/vitest` let you wait for the workflow to reach a specific point before resuming. See the [API Reference](/docs/api-reference/workflow-api) for the full list of available functions.
+</Callout>
+
+<Callout type="info">
+`waitForSleep()` returns the first **pending** sleep — one that has a `wait_created` event but no corresponding `wait_completed` event. If your workflow has multiple parallel sleeps, `waitForSleep()` returns whichever is found first. After waking one, call `waitForSleep()` again to get the next pending one. For sequential sleeps, `waitForSleep()` naturally returns each one as the workflow reaches it.
+</Callout>
+
+### Testing Webhooks
+
+Webhooks are hooks that receive HTTP `Request` objects. In tests, resume them using [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) with a `Request` payload — no HTTP server needed:
+
+```typescript title="workflows/ingest.ts" lineNumbers
+import { createWebhook } from "workflow";
+
+export async function ingestWorkflow(endpointId: string) {
+  "use workflow";
+
+  // Webhook tokens are always randomly generated
+  using webhook = createWebhook(); // [!code highlight]
+
+  const request = await webhook; // [!code highlight]
+  const body = await request.text();
+  const data = await parsePayload(body);
+
+  return { endpointId, received: data };
+}
+
+async function parsePayload(body: string) {
+  "use step";
+  return JSON.parse(body);
+}
+```
+
+```typescript title="workflows/ingest.integration.test.ts" lineNumbers
+import { describe, it, expect } from "vitest";
+import { start, resumeWebhook } from "workflow/api"; // [!code highlight]
+import { waitForHook } from "@workflow/vitest"; // [!code highlight]
+import { ingestWorkflow } from "./ingest";
+
+describe("ingestWorkflow", () => {
+  it("should process webhook data", async () => {
+    const run = await start(ingestWorkflow, ["ep-1"]);
+
+    // Discover the randomly generated webhook token
+    const hook = await waitForHook(run); // [!code highlight]
+
+    // Resume the webhook with a Request object
+    await resumeWebhook( // [!code highlight]
+      hook.token, // [!code highlight]
+      new Request("https://example.com/webhook", { // [!code highlight]
+        method: "POST", // [!code highlight]
+        body: JSON.stringify({ event: "order.created", orderId: "123" }), // [!code highlight]
+      }) // [!code highlight]
+    ); // [!code highlight]
+
+    const result = await run.returnValue;
+    expect(result).toEqual({
+      endpointId: "ep-1",
+      received: { event: "order.created", orderId: "123" },
+    });
+  });
+});
+```
+
+### Manual Setup
+
+If you need more control over the test lifecycle, the plugin also exports the individual setup functions:
+
+```typescript title="vitest.integration.config.ts" lineNumbers
+import { defineConfig } from "vitest/config";
+import { workflowTransformPlugin } from "@workflow/rollup";
+
+export default defineConfig({
+  plugins: [workflowTransformPlugin()],
+  test: {
+    include: ["**/*.integration.test.ts"],
+    testTimeout: 60_000,
+    globalSetup: "./vitest.integration.setup.ts",
+    setupFiles: ["./vitest.integration.env.ts"],
+  },
+});
+```
+
+```typescript title="vitest.integration.setup.ts"
+import { buildWorkflowTests } from "@workflow/vitest";
+
+export async function setup() {
+  await buildWorkflowTests();
+}
+```
+
+```typescript title="vitest.integration.env.ts"
+import { beforeAll, afterAll } from "vitest";
+import {
+  setupWorkflowTests,
+  teardownWorkflowTests,
+} from "@workflow/vitest";
+
+beforeAll(async () => {
+  await setupWorkflowTests();
+});
+
+afterAll(async () => {
+  await teardownWorkflowTests();
+});
+```
+
+<Callout type="info">
+`setupWorkflowTests()` automatically clears all workflow data (runs, events, hooks) on each invocation, ensuring full test isolation between test files.
+</Callout>
+
+<Callout type="info">
+For advanced setups that require a running server (e.g. testing against your actual framework's HTTP layer), see [Server-based integration testing](/docs/testing/server-based).
 </Callout>
 
 ## Debugging Test Runs
 
-When integration tests fail, the [Workflow DevKit CLI and Web UI](/docs/observability) can help you inspect what happened. Because integration tests persist workflow state to `WORKFLOW_LOCAL_DATA_DIR`, you can use the same observability tools you would use in development.
+When integration tests fail, the [Workflow DevKit CLI and Web UI](/docs/observability) can help you inspect what happened. Because integration tests persist workflow state locally, you can use the same observability tools you would use in development.
 
 Launch the Web UI to visually explore your test workflow runs:
 
@@ -357,9 +408,12 @@ Integration tests are the right place to verify that your workflows handle error
 - [Hooks & Webhooks](/docs/foundations/hooks) - Pausing and resuming workflows with external data
 - [`start()` API Reference](/docs/api-reference/workflow-api/start) - Start workflows programmatically
 - [`resumeHook()` API Reference](/docs/api-reference/workflow-api/resume-hook) - Resume hooks with data
+- [`resumeWebhook()` API Reference](/docs/api-reference/workflow-api/resume-webhook) - Resume webhooks with Request objects
 - [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Check workflow run status and wake up sleeping runs
+- [`@workflow/vitest` API Reference](/docs/api-reference/vitest) - Test helpers: `waitForSleep()`, `waitForHook()`, and plugin setup
 - [Vite Integration](/docs/getting-started/vite) - Set up the Vite plugin
 - [Observability](/docs/observability) - Inspect and debug workflow runs with the CLI and Web UI
+- [Server-based testing](/docs/testing/server-based) - Integration testing with a running server
 
 ---
 

package/docs/testing/meta.json

@@ -1,4 +1,5 @@
 {
   "title": "Testing",
-  "pages": ["testing"]
+  "pages": ["index", "server-based"],
+  "defaultOpen": false
 }

package/docs/testing/server-based.mdx

@@ -0,0 +1,183 @@
+---
+title: Server-Based Testing
+description: Integration test workflows against a running server when you need to test the full HTTP layer.
+---
+
+The [Vitest plugin](/docs/testing#integration-testing-with-the-vitest-plugin) runs workflows entirely in-process and is the recommended approach for most testing scenarios. However, there are cases where you may want to test against a running server:
+
+- Testing the full HTTP layer (middleware, authentication, request handling)
+- Reproducing behavior that only occurs in a specific framework's runtime (e.g. Next.js, Nitro)
+- Testing webhook endpoints that receive real HTTP requests
+
+This guide shows how to set up integration tests that spawn a dev server as a sidecar process. The example below uses [Nitro](https://v3.nitro.build), but the same pattern works with any supported server framework. It is meant as a starting point — customize the server setup to match your own deployment environment.
+
+## Vitest Configuration
+
+Create a Vitest config with the `workflow()` Vite plugin for code transforms and a `globalSetup` script that manages the server lifecycle:
+
+```typescript title="vitest.server.config.ts" lineNumbers
+import { defineConfig } from "vitest/config";
+import { workflow } from "workflow/vite"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [workflow()], // [!code highlight]
+  test: {
+    include: ["**/*.server.test.ts"],
+    testTimeout: 60_000,
+    globalSetup: "./vitest.server.setup.ts", // [!code highlight]
+    env: {
+      WORKFLOW_LOCAL_BASE_URL: "http://localhost:4000", // [!code highlight]
+    },
+  },
+});
+```
+
+<Callout type="info">
+Note the import path: `workflow/vite` (not `@workflow/vitest`). The Vite plugin handles code transforms but does not set up in-process execution. The server handles workflow execution instead.
+</Callout>
+
+## Global Setup Script
+
+The `globalSetup` script starts a dev server before tests run and tears it down afterwards. This example uses [Nitro](https://v3.nitro.build), but you can use any server framework that supports the workflow runtime.
+
+```typescript title="vitest.server.setup.ts" lineNumbers
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import type { ChildProcess } from "node:child_process";
+
+let server: ChildProcess | null = null;
+const PORT = "4000";
+
+export async function setup() { // [!code highlight]
+  console.log("Starting server for workflow execution...");
+
+  server = spawn("npx", ["nitro", "dev", "--port", PORT], {
+    stdio: "pipe",
+    detached: false,
+    env: process.env,
+  });
+
+  // Wait for the server to be ready
+  const ready = await new Promise<boolean>((resolve) => {
+    const timeout = setTimeout(() => resolve(false), 15_000);
+
+    server?.stdout?.on("data", (data) => {
+      const output = data.toString();
+      console.log("[server]", output);
+      if (output.includes("listening") || output.includes("ready")) {
+        clearTimeout(timeout);
+        resolve(true);
+      }
+    });
+
+    server?.stderr?.on("data", (data) => {
+      console.error("[server]", data.toString());
+    });
+
+    server?.on("error", (error) => {
+      console.error("Failed to start server:", error);
+      clearTimeout(timeout);
+      resolve(false);
+    });
+  });
+
+  if (!ready) {
+    throw new Error("Server failed to start within 15 seconds");
+  }
+
+  await delay(2_000); // Allow full initialization
+
+  // Point the workflow runtime at the local server
+  process.env.WORKFLOW_LOCAL_BASE_URL = `http://localhost:${PORT}`; // [!code highlight]
+
+  console.log("Server ready for workflow execution");
+}
+
+export async function teardown() { // [!code highlight]
+  if (server) {
+    console.log("Stopping server...");
+    server.kill("SIGTERM");
+    await delay(1_000);
+    if (!server.killed) {
+      server.kill("SIGKILL");
+    }
+  }
+}
+```
+
+The setup script sets `WORKFLOW_LOCAL_BASE_URL` so the workflow runtime sends step execution requests to the running server.
+
+<Callout type="info">
+You can use any server framework that supports the workflow runtime. The example above uses [Nitro](https://v3.nitro.build), but you could also use [Next.js](https://nextjs.org), [Hono](https://hono.dev), or any other supported server.
+</Callout>
+
+## Writing Tests
+
+Tests are written the same way as [in-process integration tests](/docs/testing#writing-integration-tests). You can use the same programmatic APIs — [`start()`](/docs/api-reference/workflow-api/start), [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook), [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook), and [`getRun().wakeUp()`](/docs/api-reference/workflow-api/get-run) — to control workflow execution:
+
+```typescript title="workflows/calculate.server.test.ts" lineNumbers
+import { describe, it, expect } from "vitest";
+import { start, getRun, resumeHook } from "workflow/api";
+import { calculateWorkflow } from "./calculate";
+import { approvalWorkflow } from "./approval";
+
+describe("calculateWorkflow", () => {
+  it("should compute the correct result", async () => {
+    const run = await start(calculateWorkflow, [2, 7]);
+    const result = await run.returnValue;
+
+    expect(result).toEqual({
+      sum: 9,
+      product: 14,
+      combined: 23,
+    });
+  });
+});
+
+describe("approvalWorkflow", () => {
+  it("should publish when approved", async () => {
+    const run = await start(approvalWorkflow, ["doc-1"]);
+
+    // Use resumeHook and wakeUp to control workflow execution
+    await resumeHook("approval:doc-1", {
+      approved: true,
+      reviewer: "alice",
+    });
+
+    await getRun(run.runId).wakeUp();
+
+    const result = await run.returnValue;
+    expect(result).toEqual({
+      status: "published",
+      reviewer: "alice",
+    });
+  });
+});
+```
+
+<Callout type="info">
+In server-based tests, the `waitForSleep()` and `waitForHook()` helpers from `@workflow/vitest` are not available since there is no in-process world. Instead, use the programmatic APIs directly — you may need to add short delays or polling to ensure the workflow has reached the desired state before resuming.
+</Callout>
+
+## Running Tests
+
+Add a script to your `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "vitest",
+    "test:server": "vitest --config vitest.server.config.ts"
+  }
+}
+```
+
+## When to Use This Approach
+
+| Scenario | Recommended approach |
+| --- | --- |
+| Testing workflow logic, steps, hooks, retries | [In-process plugin](/docs/testing) |
+| Testing HTTP middleware or authentication | Server-based |
+| Testing webhook endpoints with real HTTP | Server-based |
+| CI/CD pipeline testing | [In-process plugin](/docs/testing) |
+| Reproducing framework-specific behavior | Server-based |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.2.0-beta.64",
+  "version": "4.2.0-beta.66",
   "description": "Workflow DevKit - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -52,17 +52,17 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.0-beta.38",
-    "@workflow/cli": "4.2.0-beta.64",
-    "@workflow/core": "4.2.0-beta.64",
+    "@workflow/astro": "4.0.0-beta.40",
+    "@workflow/core": "4.2.0-beta.66",
     "@workflow/errors": "4.1.0-beta.18",
+    "@workflow/cli": "4.2.0-beta.66",
     "@workflow/typescript-plugin": "4.0.1-beta.5",
-    "@workflow/next": "4.0.1-beta.60",
-    "@workflow/nest": "0.0.0-beta.13",
-    "@workflow/nitro": "4.0.1-beta.59",
-    "@workflow/nuxt": "4.0.1-beta.48",
-    "@workflow/sveltekit": "4.0.0-beta.53",
-    "@workflow/rollup": "4.0.0-beta.21"
+    "@workflow/next": "4.0.1-beta.62",
+    "@workflow/nest": "0.0.0-beta.15",
+    "@workflow/nitro": "4.0.1-beta.61",
+    "@workflow/nuxt": "4.0.1-beta.50",
+    "@workflow/sveltekit": "4.0.0-beta.55",
+    "@workflow/rollup": "4.0.0-beta.23"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",