[vitest] [world-local] Fix local-world data recovery isolation (#1895)

Author: VaguelySerious

.changeset/moody-rivers-play.md

@@ -0,0 +1,4 @@
+---
+---
+
+Tighten cleanup in `dev.test.ts` `should include steps discovered from workflow imports` so the deferred builder drops the discovered step from the manifest before the next test file runs. Avoids a Windows-only race where the generated step route retains an import to a deleted source file and breaks every subsequent step request.

.changeset/swift-cobras-repair.md

@@ -0,0 +1,6 @@
+---
+"@workflow/vitest": patch
+"@workflow/world-local": patch
+---
+
+Fix local-world recovery isolation in Vitest and support custom test directories

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

@@ -22,6 +22,30 @@ export default defineConfig({
 });
 ```
 
+Pass a [`WorkflowTestOptions`](#workflowtestoptions) object when your project uses a non-standard layout — for example, a monorepo where `workflows/` does not live at the Vitest config's directory, or when the default `.workflow-data` / `.workflow-vitest` output locations need to move. The plugin forwards these paths to `buildWorkflowTests()` and `setupWorkflowTests()` through Vitest's per-project provided context, so each Vitest workspace project stays isolated.
+
+{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
+
+```typescript
+import { defineConfig } from "vitest/config";
+import { workflow } from "@workflow/vitest";
+
+export default defineConfig({
+  plugins: [
+    workflow({
+      cwd: "./apps/api",
+      rootDir: "./apps/api/test-artifacts",
+    }),
+  ],
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options?` | `WorkflowTestOptions` | Optional configuration |
+
 **Returns:** `Plugin[]`
 
 ## Setup Functions
@@ -83,7 +107,10 @@ Tears down the workflow test world. Clears the global world and closes the Local
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `cwd` | `string` | `process.cwd()` | The working directory of the project (where `workflows/` lives) |
+| `cwd` | `string` | `process.cwd()` | The working directory of the project (where `workflows/` lives). Relative paths resolve against `process.cwd()`. |
+| `rootDir` | `string` | same as `cwd` | Root directory used for default test artifacts. When set, `dataDir` and `outDir` default to `<rootDir>/.workflow-data` and `<rootDir>/.workflow-vitest`. Relative paths resolve against `cwd`. |
+| `dataDir` | `string` | `<rootDir>/.workflow-data` | Directory for workflow runtime data written by the test world. Relative paths resolve against `cwd`. |
+| `outDir` | `string` | `<rootDir>/.workflow-vitest` | Directory for generated workflow and step bundles. Relative paths resolve against `cwd`. |
 
 ## Test Helpers
 

packages/core/e2e/dev.test.ts

@@ -150,15 +150,20 @@ export function createDevTests(config?: DevTestConfig) {
     });
 
     afterEach(async () => {
+      // Restore file contents before deleting any files. If a deletion races
+      // ahead of an api-file restore, the dev server briefly sees an import
+      // pointing at a missing module and fails compilation. On Windows that
+      // failure can stick — Turbopack leaves stale imports in the generated
+      // step route bundle — and every subsequent step request returns 500.
+      const toRestore = restoreFiles.filter((item) => item.content !== '');
+      const toDelete = restoreFiles.filter((item) => item.content === '');
       await Promise.all(
-        restoreFiles.map(async (item) => {
-          if (item.content === '') {
-            await fs.unlink(item.path);
-          } else {
-            await fs.writeFile(item.path, item.content);
-          }
-        })
+        toRestore.map((item) => fs.writeFile(item.path, item.content))
       );
+      if (toDelete.length > 0) {
+        await prewarm();
+      }
+      await Promise.all(toDelete.map((item) => fs.unlink(item.path)));
       await prewarm();
       restoreFiles.length = 0;
     });
@@ -251,12 +256,27 @@ export async function ${marker}() {
         );
         restoreFiles.push({ path: importedStepFile, content });
 
+        const apiFile = path.join(appPath, finalConfig.apiFilePath);
+        const apiFileContent = await fs.readFile(apiFile, 'utf8');
+
         await pollUntil({
           description:
             'manifest.json to include imported step hot-reload marker',
           timeoutMs: 50_000,
           check: async () => {
-            await triggerWorkflowRun('importedStepOnlyWorkflow');
+            try {
+              await triggerWorkflowRun('importedStepOnlyWorkflow');
+            } catch (error) {
+              // Turbopack on Windows occasionally caches a stale resolver
+              // failure (e.g. `Could not parse module
+              // '@workflow/core/dist/runtime/start.js'`) after an HMR
+              // cascade and returns 500 to every request until something
+              // invalidates its cache. Rewriting the api file is enough to
+              // force a fresh resolve on the next request, so we treat the
+              // 500 as transient and keep polling instead of bailing out.
+              await fs.writeFile(apiFile, apiFileContent);
+              throw error;
+            }
             const manifestFunctionNames = await readManifestStepFunctionNames();
             expect(manifestFunctionNames).toContain(marker);
           },
@@ -311,7 +331,7 @@ ${apiFileContent}`
 
     test.skipIf(!usesDeferredBuilder)(
       'should include steps discovered from workflow imports',
-      { timeout: 30_000 },
+      { timeout: 60_000 },
       async () => {
         const workflowFile = path.join(
           appPath,
@@ -369,6 +389,39 @@ ${apiFileContent}`
             );
           },
         });
+
+        // Tear down in-test (rather than relying on afterEach) so we can wait
+        // for the deferred builder to drop the discovered step from the
+        // manifest before the next test file runs. The generated step route
+        // bundle holds a literal `import '../workflows/discovered-via-workflow-step.ts'`
+        // that is only pruned when the deferred builder rebuilds and
+        // `filterExistingFiles` excludes the now-missing source. On Windows
+        // the rebuild can lag behind the deletion, leaving the bundle
+        // unable to compile and breaking every step request in subsequent
+        // tests (which all share the same dev server).
+        await fs.writeFile(apiFile, apiFileContent);
+        await fs.unlink(workflowFile);
+        await fs.unlink(stepFile);
+        for (const trackedPath of [apiFile, workflowFile, stepFile]) {
+          const idx = restoreFiles.findIndex(
+            (item) => item.path === trackedPath
+          );
+          if (idx !== -1) {
+            restoreFiles.splice(idx, 1);
+          }
+        }
+        await pollUntil({
+          description:
+            'manifest.json to drop discoveredViaWorkflowStep after cleanup',
+          timeoutMs: 25_000,
+          check: async () => {
+            await fetchWithTimeout('/api/chat');
+            const manifestFunctionNames = await readManifestStepFunctionNames();
+            expect(manifestFunctionNames).not.toContain(
+              'discoveredViaWorkflowStep'
+            );
+          },
+        });
       }
     );
 

packages/vitest/package.json

@@ -26,7 +26,8 @@
   "scripts": {
     "build": "tsc",
     "clean": "tsc --build --clean && rm -rf dist ||:",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "test": "vitest run src"
   },
   "dependencies": {
     "@workflow/builders": "workspace:*",
@@ -38,7 +39,8 @@
   "devDependencies": {
     "@types/node": "catalog:",
     "@workflow/tsconfig": "workspace:*",
-    "vite": "7.3.2"
+    "vite": "7.3.2",
+    "vitest": "catalog:"
   },
   "peerDependencies": {
     "vite": ">=6.0.0",

packages/vitest/src/global-setup.ts

@@ -1,5 +1,14 @@
+import type { TestProject } from 'vitest/node';
 import { buildWorkflowTests } from './index.js';
+import {
+  readProvidedWorkflowTestOptions,
+  WORKFLOW_VITEST_OPTIONS_KEY,
+} from './options.js';
 
-export async function setup() {
-  await buildWorkflowTests();
+export async function setup(project: TestProject) {
+  await buildWorkflowTests(
+    readProvidedWorkflowTestOptions(
+      project.config.provide?.[WORKFLOW_VITEST_OPTIONS_KEY]
+    )
+  );
 }