workflow 4.1.0-beta.63 → 4.2.0-beta.65

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/create-hook.mdx

@@ -100,7 +100,7 @@ export async function slackBotWorkflow(channelId: string) {
 
   // Token constructed from channel ID
   using hook = createHook<SlackMessage>({ // [!code highlight]
-    token: `slack_webhook:${channelId}`, // [!code highlight]
+    token: `slack_messages:${channelId}`, // [!code highlight]
   }); // [!code highlight]
 
   for await (const message of hook) {

package/docs/api-reference/workflow/create-webhook.mdx

@@ -120,46 +120,6 @@ async function processData(data: any) {
 }
 ```
 
-### Customizing Tokens
-
-Tokens are used to identify a specific webhook. You can customize the token to be more specific to a use case.
-
-```typescript lineNumbers
-import { createWebhook, type RequestWithResponse } from "workflow"
-
-async function sendAck(request: RequestWithResponse) {
-  "use step";
-  await request.respondWith(
-    new Response(JSON.stringify({ received: true }), {
-      headers: { "Content-Type": "application/json" }
-    })
-  );
-}
-
-export async function githubWebhookWorkflow(repoName: string) {
-  "use workflow";
-
-  // Use a deterministic token based on the repository
-  using webhook = createWebhook({ // [!code highlight]
-    token: `github_webhook:${repoName}`, // [!code highlight]
-  }); // [!code highlight]
-
-  console.log("Configure GitHub webhook:", webhook.url);
-
-  const request = await webhook;
-  const event = await request.json();
-
-  await sendAck(request);
-
-  await deployCommit(event);
-}
-
-async function deployCommit(event: any) {
-  "use step";
-  // Deploy logic here
-}
-```
-
 ### Waiting for Multiple Requests
 
 You can also wait for multiple requests by using the `for await...of` syntax.
@@ -167,62 +127,35 @@ You can also wait for multiple requests by using the `for await...of` syntax.
 ```typescript lineNumbers
 import { createWebhook, type RequestWithResponse } from "workflow"
 
-async function sendSlackResponse(request: RequestWithResponse, message: string) {
+async function sendAck(request: RequestWithResponse, message: string) {
   "use step";
   await request.respondWith(
-    new Response(
-      JSON.stringify({
-        response_type: "in_channel",
-        text: message
-      }),
-      { headers: { "Content-Type": "application/json" } }
-    )
+    Response.json({ received: true, message })
   );
 }
 
-async function sendStopResponse(request: RequestWithResponse) {
+async function processEvent(data: any) {
   "use step";
-  await request.respondWith(
-    new Response("Stopping workflow...")
-  );
+  console.log("Processing event:", data);
 }
 
-export async function slackCommandWorkflow(channelId: string) {
+export async function eventCollectorWorkflow() {
   "use workflow";
 
-  using webhook = createWebhook({
-    token: `slack_command:${channelId}`,
-  });
+  using webhook = createWebhook({ respondWith: "manual" });
+  console.log("Send events to:", webhook.url);
 
   for await (const request of webhook) { // [!code highlight]
-    const formData = await request.formData();
-    const command = formData.get("command");
-    const text = formData.get("text");
+    const data = await request.json();
 
-    if (command === "/status") {
-      // Respond immediately to Slack
-      await sendSlackResponse(request, "Checking status...");
-
-      // Process the command
-      const status = await checkSystemStatus();
-      await postToSlack(channelId, `Status: ${status}`);
-    }
-
-    if (text === "stop") {
-      await sendStopResponse(request);
+    if (data.type === "done") {
+      await sendAck(request, "Workflow complete");
       break;
     }
-  }
-}
-
-async function checkSystemStatus() {
-  "use step";
-  return "All systems operational";
-}
 
-async function postToSlack(channelId: string, message: string) {
-  "use step";
-  // Post message to Slack
+    await sendAck(request, "Event received");
+    await processEvent(data);
+  }
 }
 ```
 

package/docs/api-reference/workflow-api/resume-webhook.mdx

@@ -56,11 +56,17 @@ Returns a `Promise<Response>` that resolves to:
 
 Throws an error if the webhook token is not found or invalid.
 
-## Examples
+## Usage Note
 
-### Basic API Route
+<Callout type="warn">
+In most cases, you should not need to call `resumeWebhook()` directly. When you use `createWebhook()`, the framework automatically generates a random webhook token and provides a public URL at `/.well-known/workflow/v1/webhook/:token`. External systems can send HTTP requests directly to that URL.
+
+For server-side hook resumption with deterministic tokens, use [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) with [`createHook()`](/docs/api-reference/workflow/create-hook) instead.
+</Callout>
 
-Forward incoming HTTP requests to a webhook by token:
+## Example
+
+Forward an incoming HTTP request to a webhook by token:
 
 ```typescript lineNumbers
 import { resumeWebhook } from "workflow/api";
@@ -82,159 +88,6 @@ export async function POST(request: Request) {
 }
 ```
 
-### GitHub Webhook Handler
-
-Handle GitHub webhook events and forward them to workflows:
-
-```typescript lineNumbers
-import { resumeWebhook } from "workflow/api";
-import { verifyGitHubSignature } from "@/lib/github";
-
-export async function POST(request: Request) {
-  // Extract repository name from URL
-  const url = new URL(request.url);
-  const repo = url.pathname.split("/").pop();
-
-  // Verify GitHub signature
-  const signature = request.headers.get("x-hub-signature-256");
-  const isValid = await verifyGitHubSignature(request, signature);
-
-  if (!isValid) {
-    return new Response("Invalid signature", { status: 401 });
-  }
-
-  // Construct deterministic token
-  const token = `github_webhook:${repo}`;
-
-  try {
-    const response = await resumeWebhook(token, request); // [!code highlight]
-    return response;
-  } catch (error) {
-    return new Response("Workflow not found", { status: 404 });
-  }
-}
-```
-
-### Slack Slash Command Handler
-
-Process Slack slash commands and route them to workflow webhooks:
-
-```typescript lineNumbers
-import { resumeWebhook } from "workflow/api";
-
-export async function POST(request: Request) {
-  const formData = await request.formData();
-  const channelId = formData.get("channel_id") as string;
-  const command = formData.get("command") as string;
-
-  // Verify Slack request signature
-  const slackSignature = request.headers.get("x-slack-signature");
-  if (!slackSignature) {
-    return new Response("Unauthorized", { status: 401 });
-  }
-
-  // Construct token from channel ID
-  const token = `slack_command:${channelId}`;
-
-  try {
-    const response = await resumeWebhook(token, request); // [!code highlight]
-    return response;
-  } catch (error) {
-    // If no workflow is listening, return a default response
-    return new Response(
-      JSON.stringify({
-        response_type: "ephemeral",
-        text: "No active workflow for this channel"
-      }),
-      {
-        headers: { "Content-Type": "application/json" }
-      }
-    );
-  }
-}
-```
-
-### Multi-Tenant Webhook Router
-
-Route webhooks to different workflows based on tenant/organization:
-
-```typescript lineNumbers
-import { resumeWebhook } from "workflow/api";
-
-export async function POST(request: Request) {
-  const url = new URL(request.url);
-
-  // Extract tenant and webhook ID from path
-  // e.g., /api/webhooks/tenant-123/webhook-abc
-  const [, , , tenantId, webhookId] = url.pathname.split("/");
-
-  if (!tenantId || !webhookId) {
-    return new Response("Invalid webhook URL", { status: 400 });
-  }
-
-  // Verify API key for tenant
-  const apiKey = request.headers.get("authorization");
-  const isAuthorized = await verifyTenantApiKey(tenantId, apiKey);
-
-  if (!isAuthorized) {
-    return new Response("Unauthorized", { status: 401 });
-  }
-
-  // Construct namespaced token
-  const token = `tenant:${tenantId}:webhook:${webhookId}`;
-
-  try {
-    const response = await resumeWebhook(token, request); // [!code highlight]
-    return response;
-  } catch (error) {
-    return new Response("Webhook not found or expired", { status: 404 });
-  }
-}
-
-async function verifyTenantApiKey(tenantId: string, apiKey: string | null) {
-  // Verify API key logic
-  return apiKey === process.env[`TENANT_${tenantId}_API_KEY`];
-}
-```
-
-### Server Action (Next.js)
-
-Use `resumeWebhook` in a Next.js server action:
-
-```typescript lineNumbers
-"use server";
-
-import { resumeWebhook } from "workflow/api";
-
-export async function triggerWebhook(
-  token: string,
-  payload: Record<string, any>
-) {
-  // Create a Request object from the payload
-  const request = new Request("http://localhost/webhook", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(payload),
-  });
-
-  try {
-    const response = await resumeWebhook(token, request);
-
-    // Parse and return the response
-    const contentType = response.headers.get("content-type");
-    if (contentType?.includes("application/json")) {
-      return await response.json();
-    }
-
-    return await response.text();
-  } catch (error) {
-    throw new Error("Webhook not found");
-  }
-}
-```
-
 ## Related Functions
 
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Create a webhook in a workflow

package/docs/foundations/hooks.mdx

@@ -339,53 +339,36 @@ Like hooks, webhooks support iteration:
 ```typescript lineNumbers
 import { createWebhook, type RequestWithResponse } from "workflow";
 
-async function respondToSlack(request: RequestWithResponse, text: string) {
+async function sendAck(request: RequestWithResponse, message: string) {
   "use step";
 
   await request.respondWith(
-    new Response(
-      JSON.stringify({ response_type: "in_channel", text }),
-      { headers: { "Content-Type": "application/json" } }
-    )
+    Response.json({ received: true, message })
   );
 }
 
-export async function slackCommandWorkflow(channelId: string) {
-  "use workflow";
+async function processEvent(data: any) {
+  "use step";
+  console.log("Processing event:", data);
+}
 
-  using webhook = createWebhook({
-    token: `slack_command:${channelId}`,
-    respondWith: "manual"
-  });
+export async function eventCollectorWorkflow() {
+  "use workflow";
 
-  console.log("Configure Slack command webhook:", webhook.url);
+  using webhook = createWebhook({ respondWith: "manual" });
+  console.log("Send events to:", webhook.url);
 
   for await (const request of webhook) {
-    const formData = await request.formData();
-    const command = formData.get("command");
-    const text = formData.get("text");
-
-    if (command === "/status") {
-      await respondToSlack(request, "Checking status...");
-      const status = await checkSystemStatus();
-      await postToSlack(channelId, `Status: ${status}`);
-    }
+    const data = await request.json();
 
-    if (text === "stop") {
-      await respondToSlack(request, "Stopping workflow...");
+    if (data.type === "done") {
+      await sendAck(request, "Workflow complete");
       break;
     }
-  }
-}
 
-async function checkSystemStatus() {
-  "use step";
-  return "All systems operational";
-}
-
-async function postToSlack(channelId: string, message: string) {
-  "use step";
-  // Post message to Slack
+    await sendAck(request, "Event received");
+    await processEvent(data);
+  }
 }
 ```
 
@@ -464,7 +447,9 @@ This pattern is especially valuable in larger applications where the workflow an
 
 ### Token Design
 
-When using custom tokens:
+Custom tokens are available for `createHook()` with server-side `resumeHook()` only. Webhooks (`createWebhook()`) always use randomly generated tokens to prevent unauthorized access to public webhook endpoints.
+
+When using custom tokens with `createHook()`:
 
 - **Make them deterministic**: Base them on data the external system can reconstruct (like channel IDs, user IDs, etc.)
 - **Use namespacing**: Prefix tokens to avoid conflicts (e.g., `slack:${channelId}`, `github:${repoId}`)

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.1.0-beta.63",
+  "version": "4.2.0-beta.65",
   "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.37",
-    "@workflow/cli": "4.1.0-beta.63",
-    "@workflow/core": "4.1.0-beta.63",
-    "@workflow/errors": "4.1.0-beta.17",
+    "@workflow/astro": "4.0.0-beta.39",
+    "@workflow/cli": "4.2.0-beta.65",
+    "@workflow/core": "4.2.0-beta.65",
+    "@workflow/errors": "4.1.0-beta.18",
     "@workflow/typescript-plugin": "4.0.1-beta.5",
-    "@workflow/next": "4.0.1-beta.59",
-    "@workflow/nest": "0.0.0-beta.12",
-    "@workflow/nitro": "4.0.1-beta.58",
-    "@workflow/nuxt": "4.0.1-beta.47",
-    "@workflow/sveltekit": "4.0.0-beta.52",
-    "@workflow/rollup": "4.0.0-beta.20"
+    "@workflow/next": "4.0.1-beta.61",
+    "@workflow/nest": "0.0.0-beta.14",
+    "@workflow/nitro": "4.0.1-beta.60",
+    "@workflow/nuxt": "4.0.1-beta.49",
+    "@workflow/sveltekit": "4.0.0-beta.54",
+    "@workflow/rollup": "4.0.0-beta.22"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",