feat(vitest-pool-workers): step-through debugging (#8199)

Co-authored-by: Somhairle MacLeòid <smacleod@cloudflare.com>

Author: edmundhung

Diff for: .changeset/small-news-kneel.md

@@ -0,0 +1,13 @@
+---
+"@cloudflare/vitest-pool-workers": patch
+---
+
+Added step-through debugging support with Vitest.
+
+To start debugging, run Vitest with the following command and attach a debugger to port 9229:
+
+```sh
+vitest --inspect=9229 --no-file-parallelism
+```
+
+For more details, check out our [Vitest Debugging guide](https://developers.cloudflare.com/workers/testing/vitest-integration/debugging).

Diff for: packages/vitest-pool-workers/src/pool/index.ts

@@ -556,13 +556,24 @@ function buildProjectMiniflareOptions(
 	assert(runnerWorker.name !== undefined);
 	assert(runnerWorker.name.startsWith(WORKER_NAME_PREFIX));
 
+	const inspectorPort = ctx.config.inspector.enabled
+		? ctx.config.inspector.port ?? 9229
+		: undefined;
+
+	if (inspectorPort !== undefined && !project.options.singleWorker) {
+		log.warn(`Tests run in singleWorker mode when the inspector is open.`);
+
+		project.options.singleWorker = true;
+	}
+
 	if (project.options.singleWorker || project.options.isolatedStorage) {
 		// Single Worker, Isolated or Shared Storage
 		//  --> single instance with single runner worker
 		// Multiple Workers, Isolated Storage:
 		//  --> multiple instances each with single runner worker
 		return {
 			...SHARED_MINIFLARE_OPTIONS,
+			inspectorPort,
 			unsafeModuleFallbackService: moduleFallbackService,
 			workers: [runnerWorker, ABORT_ALL_WORKER, ...auxiliaryWorkers],
 		};
@@ -610,7 +621,11 @@ async function getProjectMiniflare(
 	if (project.mf === undefined) {
 		// If `mf` is now `undefined`, create new instances
 		if (singleInstance) {
-			log.info(`Starting single runtime for ${project.relativePath}...`);
+			log.info(
+				`Starting single runtime for ${project.relativePath}` +
+					`${mfOptions.inspectorPort !== undefined ? ` with inspector on port ${mfOptions.inspectorPort}` : ""}` +
+					`...`
+			);
 			project.mf = new Miniflare(mfOptions);
 		} else {
 			log.info(`Starting isolated runtimes for ${project.relativePath}...`);
@@ -864,6 +879,31 @@ function assertCompatibleVitestVersion(ctx: Vitest) {
 		log.warn(message);
 	}
 }
+
+let warnedUnsupportedInspectorOptions = false;
+
+function validateInspectorConfig(config: SerializedConfig) {
+	if (config.inspector.host) {
+		throw new TypeError(
+			"Customizing inspector host is not supported with vitest-pool-workers."
+		);
+	}
+
+	if (config.inspector.enabled && !warnedUnsupportedInspectorOptions) {
+		if (config.inspectBrk) {
+			log.warn(
+				`The "--inspect-brk" flag is not supported. Use "--inspect" instead.`
+			);
+		} else if (config.inspector.waitForDebugger) {
+			log.warn(
+				`The "inspector.waitForDebugger" option is not supported. Insert a debugger statement if you need to pause execution.`
+			);
+		}
+
+		warnedUnsupportedInspectorOptions = true;
+	}
+}
+
 async function executeMethod(
 	ctx: Vitest,
 	specs: TestSpecification[],
@@ -932,6 +972,13 @@ async function executeMethod(
 				timerMethod !== "setImmediate" && timerMethod !== "clearImmediate"
 		);
 
+		validateInspectorConfig(config);
+
+		// We don't want it to call `node:inspector` inside Workerd
+		config.inspector = {
+			enabled: false,
+		};
+
 		// We don't need all pool options from the config at runtime.
 		// Additionally, users may set symbols in the config which aren't
 		// serialisable. `getSerializableConfig()` may also return references to

Diff for: packages/vitest-pool-workers/test/inspector.test.ts

@@ -0,0 +1,113 @@
+import dedent from "ts-dedent";
+import { test, waitFor } from "./helpers";
+
+test("opens an inspector with the `--inspect` argument", async ({
+	expect,
+	seed,
+	vitestDev,
+}) => {
+	await seed({
+		"vitest.config.mts": dedent`
+			import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+			export default defineWorkersConfig({
+				test: {
+					poolOptions: {
+						workers: {
+							main: "./index.ts",
+							singleWorker: true,
+							miniflare: {
+								compatibilityDate: "2024-01-01",
+								compatibilityFlags: ["nodejs_compat"],
+							},
+						},
+					},
+				}
+			});
+		`,
+		"index.ts": dedent`
+			export default {
+				async fetch(request, env, ctx) {
+					return new Response("hello world");
+				}
+			}
+		`,
+		"index.test.ts": dedent`
+			import { env, createExecutionContext, waitOnExecutionContext } from "cloudflare:test";
+			import { it, expect } from "vitest";
+			import worker from "./index";
+			it("sends request", async () => {
+				const request = new Request("https://example.com");
+				const ctx = createExecutionContext();
+				const response = await worker.fetch(request, env, ctx);
+				await waitOnExecutionContext(ctx);
+				expect(await response.text()).toBe("hello world");
+			});
+		`,
+	});
+	const result = vitestDev({
+		flags: ["--inspect", "--no-file-parallelism"],
+	});
+
+	await waitFor(() => {
+		expect(result.stdout).toMatch("inspector on port 9229");
+	});
+});
+
+test("customize inspector config", async ({ expect, seed, vitestDev }) => {
+	await seed({
+		"vitest.config.mts": dedent`
+			import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+			export default defineWorkersConfig({
+				test: {
+					inspector: {
+						// Test if this overrides the inspector port
+						port: 3456,
+					},
+					poolOptions: {
+						workers: {
+							main: "./index.ts",
+							// Test if we warn and override the singleWorker option when the inspector is open
+							singleWorker: false,
+							miniflare: {
+								compatibilityDate: "2024-01-01",
+								compatibilityFlags: ["nodejs_compat"],
+							},
+						},
+					},
+				}
+			});
+		`,
+		"index.ts": dedent`
+			export default {
+				async fetch(request, env, ctx) {
+					return new Response("hello world");
+				}
+			}
+		`,
+		"index.test.ts": dedent`
+			import { env, createExecutionContext, waitOnExecutionContext } from "cloudflare:test";
+			import { it, expect } from "vitest";
+			import worker from "./index";
+			it("sends request", async () => {
+				const request = new Request("https://example.com");
+				const ctx = createExecutionContext();
+				const response = await worker.fetch(request, env, ctx);
+				await waitOnExecutionContext(ctx);
+				expect(await response.text()).toBe("hello world");
+			});
+		`,
+	});
+	const result = vitestDev({
+		// Test if we warn and ignore the `waitForDebugger` option
+		flags: ["--inspect-brk", "--no-file-parallelism"],
+	});
+
+	await waitFor(() => {
+		expect(result.stdout).toMatch(
+			"Tests run in singleWorker mode when the inspector is open."
+		);
+		expect(result.stdout).toMatch(`The "--inspect-brk" flag is not supported.`);
+		expect(result.stdout).toMatch("Starting single runtime");
+		expect(result.stdout).toMatch("inspector on port 3456");
+	});
+});