fix: --inspect to work inside workers

docs/guide/debugging.md

@@ -45,3 +45,19 @@ JavaScript file | ./node_modules/vitest/vitest.mjs
 Application parameters | run --threads false
 
 Then run this configuration in debug mode. The IDE will stop at JS/TS breakpoints set in the editor.
+
+## Node Inspector, e.g. Chrome DevTools
+
+Vitest also supports debugging tests without IDEs. However this requires that tests are not run parallel. Use one of the following commands to launch Vitest.
+
+```sh
+# To run in a single worker
+vitest --inspect-brk --single-thread
+
+# To run in a child process
+vitest --inspect-brk --no-threads
+```
+
+Once Vitest starts it will stop execution and waits for you to open developer tools that can connect to [NodeJS inspector](https://nodejs.org/en/docs/guides/debugging-getting-started/). You can use Chrome DevTools for this by opening `chrome://inspect` on browser.
+
+In watch mode you can keep the debugger open during test re-runs by using the `--single-thread --isolate false` options.

packages/vitest/src/node/cli-wrapper.ts

@@ -11,8 +11,6 @@ const ENTRY = new URL('./cli.js', import.meta.url)
 
 /** Arguments passed to Node before the script */
 const NODE_ARGS = [
-  '--inspect',
-  '--inspect-brk',
   '--trace-deprecation',
   '--experimental-wasm-threads',
   '--wasm-atomics-on-non-shared-memory',

packages/vitest/src/node/config.ts

@@ -106,6 +106,13 @@ export function resolveConfig(
     resolved.shard = { index, count }
   }
 
+  if (resolved.inspect || resolved.inspectBrk) {
+    if (resolved.threads !== false && resolved.singleThread !== true) {
+      const inspectOption = `--inspect${resolved.inspectBrk ? '-brk' : ''}`
+      throw new Error(`You cannot use ${inspectOption} without "threads: false" or "singleThread: true"`)
+    }
+  }
+
   resolved.deps = resolved.deps || {}
   // vitenode will try to import such file with native node,
   // but then our mocker will not work properly

packages/vitest/src/runtime/child.ts

@@ -6,6 +6,7 @@ import type { RuntimeRPC } from '../types/rpc'
 import type { ChildContext } from '../types/child'
 import { mockMap, moduleCache, startViteNode } from './execute'
 import { rpcDone } from './rpc'
+import { setupInspect } from './inspector'
 
 function init(ctx: ChildContext) {
   const { config } = ctx
@@ -58,10 +59,12 @@ function unwrapConfig(config: ResolvedConfig) {
 }
 
 export async function run(ctx: ChildContext) {
+  const inspectorCleanup = setupInspect(ctx.config)
   init(ctx)
   const { run, executor } = await startViteNode(ctx)
   await run(ctx.files, ctx.config, ctx.environment, executor)
   await rpcDone()
+  inspectorCleanup()
 }
 
 const procesExit = process.exit

packages/vitest/src/runtime/inspector.ts

@@ -0,0 +1,31 @@
+import inspector from 'node:inspector'
+
+import type { ResolvedConfig } from '../types'
+
+/**
+ * Enables debugging inside `worker_threads` and `child_process`.
+ * Should be called as early as possible when worker/process has been set up.
+ */
+export function setupInspect(config: ResolvedConfig) {
+  const isEnabled = config.inspect || config.inspectBrk
+
+  if (isEnabled) {
+    // Inspector may be open already if "isolate: false" is used
+    const isOpen = inspector.url() !== undefined
+
+    if (!isOpen) {
+      inspector.open()
+
+      if (config.inspectBrk)
+        inspector.waitForDebugger()
+    }
+  }
+
+  // In watch mode the inspector can persist re-runs if "isolate: false, singleThread: true" is used
+  const keepOpen = config.watch && !config.isolate && config.singleThread
+
+  return function cleanup() {
+    if (isEnabled && !keepOpen)
+      inspector.close()
+  }
+}

packages/vitest/src/runtime/worker.ts

@@ -3,6 +3,7 @@ import { workerId as poolId } from 'tinypool'
 import type { RuntimeRPC, WorkerContext } from '../types'
 import { getWorkerState } from '../utils/global'
 import { mockMap, moduleCache, startViteNode } from './execute'
+import { setupInspect } from './inspector'
 import { rpcDone } from './rpc'
 
 function init(ctx: WorkerContext) {
@@ -43,8 +44,10 @@ function init(ctx: WorkerContext) {
 }
 
 export async function run(ctx: WorkerContext) {
+  const inspectorCleanup = setupInspect(ctx.config)
   init(ctx)
   const { run, executor } = await startViteNode(ctx)
   await run(ctx.files, ctx.config, ctx.environment, executor)
   await rpcDone()
+  inspectorCleanup()
 }

packages/vitest/src/types/config.ts

@@ -541,6 +541,20 @@ export interface InlineConfig {
    * Path to a custom test runner.
    */
   runner?: string
+
+  /**
+   * Debug tests by opening `node:inspector` in worker / child process.
+   * Provides similar experience as `--inspect` Node CLI argument.
+   * Requires `singleThread: true` OR `threads: false`.
+   */
+  inspect?: boolean
+
+  /**
+   * Debug tests by opening `node:inspector` in worker / child process and wait for debugger to connect.
+   * Provides similar experience as `--inspect-brk` Node CLI argument.
+   * Requires `singleThread: true` OR `threads: false`.
+   */
+  inspectBrk?: boolean
 }
 
 export interface TypecheckConfig {

test/config/test/failures.test.ts

@@ -19,3 +19,21 @@ test('shard index must be smaller than count', async () => {
 
   expect(error).toMatch('Error: --shard <index> must be a positive number less then <count>')
 })
+
+test('inspect requires changing threads or singleThread', async () => {
+  const { error } = await runVitest('run', ['--inspect'])
+
+  expect(error).toMatch('Error: You cannot use --inspect without "threads: false" or "singleThread: true"')
+})
+
+test('inspect cannot be used with threads', async () => {
+  const { error } = await runVitest('run', ['--inspect', '--threads', 'true'])
+
+  expect(error).toMatch('Error: You cannot use --inspect without "threads: false" or "singleThread: true"')
+})
+
+test('inspect-brk cannot be used with threads', async () => {
+  const { error } = await runVitest('run', ['--inspect-brk', '--threads', 'true'])
+
+  expect(error).toMatch('Error: You cannot use --inspect-brk without "threads: false" or "singleThread: true"')
+})