test: share one cross-platform tree-kill helper across the dev-server suites

The three spawn-based suites (process-cleanup, metro-compiler,
metro-startup-order) each carried their own killTree copy, and all three
single-killed on POSIX — so a dev server's worker processes were orphaned on
teardown (only Windows' taskkill /T walked the tree). Extract one
killProcessTree into tests/test/tests/process-tree.ts: POSIX signals the whole
process group (negative pid), Windows uses taskkill /F /T. Spawn the dev
servers detached on POSIX so the group-kill reaches their workers — mirrors
packages/test/src/setupTest.ts.

Add cross-platform positive/negative tests that pin the contract: the tree-kill
reaps the worker, while a bare single-pid kill leaves it orphaned (the reason
the tree-kill exists). Windows uses a detached worker that escapes the job
object; POSIX uses an in-group worker.

Validated on Windows 11 (process-cleanup 3 passed, metro 2 passed, oxlint/tsc
clean) and the POSIX group-kill mechanism on Linux (WSL).

Author: YevheniiKotyrlo

tests/test/tests/metro-compiler.test.ts

@@ -3,6 +3,7 @@ import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import getPort from 'get-port'
 import { describe, expect, it, afterEach } from 'vitest'
+import { killProcessTree } from './process-tree'
 
 // Resolve one's JS entry (run.mjs) instead of node_modules/.bin/one: on Windows
 // the .bin shim is a .cmd/.ps1/.exe wrapper that `node <path>` can't load
@@ -13,23 +14,6 @@ const oneRunEntry = join(
   'run.mjs'
 )
 
-// node cannot signal a process tree on Windows; taskkill /T kills spawned workers too
-function killTree(proc: ChildProcess) {
-  if (!proc.pid) return
-  if (process.platform === 'win32') {
-    try {
-      spawn('taskkill', ['/F', '/T', '/PID', String(proc.pid)], { stdio: 'ignore' })
-    } catch {}
-  } else {
-    proc.kill('SIGTERM')
-    setTimeout(() => {
-      try {
-        proc.kill('SIGKILL')
-      } catch {}
-    }, 1000)
-  }
-}
-
 /**
  * Test that the React compiler works through the Metro bundling path.
  *
@@ -50,7 +34,7 @@ describe('Metro React compiler', { retry: 1 }, () => {
 
   afterEach(() => {
     if (devServer) {
-      killTree(devServer)
+      killProcessTree(devServer.pid)
       devServer = null
     }
   })
@@ -69,6 +53,8 @@ describe('Metro React compiler', { retry: 1 }, () => {
         DEBUG: 'vxrn:*,vite-plugin-metro:*',
       },
       stdio: ['ignore', 'pipe', 'pipe'],
+      // group leader on POSIX so killProcessTree can signal the whole group
+      detached: process.platform !== 'win32',
     })
 
     devServer.on('exit', (code) => {

tests/test/tests/metro-startup-order.test.ts

@@ -1,8 +1,9 @@
-import { spawn, type ChildProcess } from 'node:child_process'
+import { spawn } from 'node:child_process'
 import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import getPort from 'get-port'
 import { describe, expect, it } from 'vitest'
+import { killProcessTree } from './process-tree'
 
 // Resolve one's JS entry (run.mjs) instead of node_modules/.bin/one: on Windows
 // the .bin shim is a .cmd/.ps1/.exe wrapper that `node <path>` can't load
@@ -13,23 +14,6 @@ const oneRunEntry = join(
   'run.mjs'
 )
 
-// node cannot signal a process tree on Windows; taskkill /T kills spawned workers too
-function killTree(proc: ChildProcess) {
-  if (!proc.pid) return
-  if (process.platform === 'win32') {
-    try {
-      spawn('taskkill', ['/F', '/T', '/PID', String(proc.pid)], { stdio: 'ignore' })
-    } catch {}
-  } else {
-    proc.kill('SIGTERM')
-    setTimeout(() => {
-      try {
-        proc.kill('SIGKILL')
-      } catch {}
-    }, 1000)
-  }
-}
-
 /**
  * Test that Metro initialization happens AFTER Vite server is fully started.
  *
@@ -61,6 +45,8 @@ describe('Metro startup order', () => {
         DEBUG: 'vxrn:*',
       },
       stdio: ['ignore', 'pipe', 'pipe'],
+      // group leader on POSIX so killProcessTree can signal the whole group
+      detached: process.platform !== 'win32',
     })
 
     const collectLogs = (data: Buffer) => {
@@ -104,8 +90,8 @@ describe('Metro startup order', () => {
       }, 100)
     })
 
-    // Kill the server (tree-kill on Windows; SIGTERM→SIGKILL on POSIX)
-    killTree(devServer)
+    // Kill the server (tree-kill: taskkill /T on Windows, process-group on POSIX)
+    killProcessTree(devServer.pid)
     await new Promise((r) => setTimeout(r, 500))
 
     // Verify the order - Vite should be ready BEFORE Metro

tests/test/tests/process-cleanup.test.ts

@@ -3,6 +3,7 @@ import { createRequire } from 'node:module'
 import { dirname, join } from 'node:path'
 import { afterEach, describe, expect, test } from 'vitest'
 import getPort from 'get-port'
+import { killProcessTree } from './process-tree'
 
 // Resolve one's JS entry (run.mjs) instead of node_modules/.bin/one: on Windows
 // the .bin shim is a .cmd/.ps1/.exe wrapper that `node <path>` can't load
@@ -13,20 +14,6 @@ const oneRunEntry = join(
   'run.mjs'
 )
 
-// node cannot signal a process tree on Windows; taskkill /T kills spawned workers too
-function killTree(proc: ChildProcess) {
-  if (!proc.pid) return
-  if (process.platform === 'win32') {
-    try {
-      spawn('taskkill', ['/F', '/T', '/PID', String(proc.pid)], { stdio: 'ignore' })
-    } catch {}
-  } else {
-    try {
-      process.kill(proc.pid, 'SIGKILL')
-    } catch {}
-  }
-}
-
 // Helper to wait for a process to exit
 function waitForExit(proc: ChildProcess, timeout = 5000): Promise<number | null> {
   return new Promise((resolve) => {
@@ -55,10 +42,10 @@ describe('process cleanup', () => {
   afterEach(() => {
     // Clean up any leftover processes (tree-kill so dev-server workers don't orphan)
     if (devServer?.pid && isRunning(devServer.pid)) {
-      killTree(devServer)
+      killProcessTree(devServer.pid)
     }
     if (wrapper?.pid && isRunning(wrapper.pid)) {
-      killTree(wrapper)
+      killProcessTree(wrapper.pid)
     }
   })
 
@@ -129,6 +116,8 @@ describe('process cleanup', () => {
     devServer = spawn('node', [oneRunEntry, 'dev', '--port', port.toString()], {
       cwd: process.cwd(),
       stdio: 'pipe',
+      // group leader on POSIX so killProcessTree can signal the whole group
+      detached: process.platform !== 'win32',
     })
 
     // Wait for dev server to start
@@ -142,7 +131,154 @@ describe('process cleanup', () => {
     await new Promise((r) => setTimeout(r, 2000))
     expect(isRunning(devServer.pid!)).toBe(true)
 
-    // Clean up (tree-kill so dev-server workers don't orphan on Windows)
-    killTree(devServer)
+    // Clean up (tree-kill so dev-server workers don't orphan)
+    killProcessTree(devServer.pid)
   }, 15000)
 })
+
+// Pins the cross-platform tree-kill contract that killProcessTree (./process-tree,
+// and packages/test/src/setup.ts) relies on. The mechanisms differ by platform, so
+// each gets a positive (the whole tree is reaped) and a negative (a bare single-PID
+// kill leaves a worker orphaned — i.e. why a plain process.kill is not enough):
+//   - Windows: process.kill(pid) is TerminateProcess and does not walk the tree; a
+//     worker that broke away from libuv's job object (detached) survives it, while
+//     taskkill /F /T walks the PID tree and reaps it.
+//   - POSIX: process.kill(pid) signals only the leader; killProcessTree signals the
+//     whole process group (negative pid), so the workers it forked go too.
+describe('process tree termination', () => {
+  const spawnedPids: number[] = []
+
+  afterEach(() => {
+    // safety net: force-kill anything a test spawned, even if it failed mid-way
+    for (const pid of spawnedPids) {
+      try {
+        if (process.platform === 'win32') {
+          spawn('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore' })
+        } else {
+          try {
+            process.kill(-pid, 'SIGKILL')
+          } catch {
+            // not a group leader
+          }
+          try {
+            process.kill(pid, 'SIGKILL')
+          } catch {
+            // already gone
+          }
+        }
+      } catch {
+        // already gone
+      }
+    }
+    spawnedPids.length = 0
+  })
+
+  // Spawn a server -> worker tree, resolving once the worker PID is known. The
+  // server is a group leader on POSIX (detached) so killProcessTree's group-kill
+  // reaches the worker; on Windows detached is irrelevant to taskkill /T. The
+  // worker is spawned detached only when we want it to escape the parent's job
+  // object / process group (the case a single-process kill cannot clean up).
+  function spawnTree(
+    detachedWorker: boolean
+  ): Promise<{ server: ChildProcess; workerPid: number }> {
+    const server = spawn(
+      'node',
+      [
+        '-e',
+        `
+        const { spawn } = require('child_process')
+        const worker = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], {
+          detached: ${detachedWorker},
+          stdio: 'ignore',
+        })
+        ${detachedWorker ? 'worker.unref()' : ''}
+        process.stdout.write('WORKER_PID=' + worker.pid + '\\n')
+        setInterval(() => {}, 1000)
+        `,
+      ],
+      { stdio: ['ignore', 'pipe', 'ignore'], detached: process.platform !== 'win32' }
+    )
+    return new Promise((resolve) => {
+      let out = ''
+      server.stdout?.on('data', (d) => {
+        out += d.toString()
+        const match = out.match(/WORKER_PID=(\d+)\r?\n/)
+        if (match) {
+          const workerPid = Number(match[1])
+          if (server.pid) spawnedPids.push(server.pid)
+          spawnedPids.push(workerPid)
+          resolve({ server, workerPid })
+        }
+      })
+    })
+  }
+
+  test.skipIf(process.platform !== 'win32')(
+    'killProcessTree reaps a detached worker that escaped the job object (Windows)',
+    async () => {
+      const { server, workerPid } = await spawnTree(true)
+      expect(server.pid).toBeTruthy()
+      expect(isRunning(server.pid!)).toBe(true)
+      expect(isRunning(workerPid)).toBe(true)
+
+      killProcessTree(server.pid)
+      await new Promise((r) => setTimeout(r, 2000))
+
+      expect(isRunning(server.pid!)).toBe(false)
+      expect(isRunning(workerPid)).toBe(false)
+    },
+    15000
+  )
+
+  test.skipIf(process.platform !== 'win32')(
+    'a bare process.kill orphans a detached worker on Windows (why tree-kill is needed)',
+    async () => {
+      const { server, workerPid } = await spawnTree(true)
+      expect(isRunning(workerPid)).toBe(true)
+
+      // TerminateProcess does not walk the tree, and the detached worker broke away
+      // from the job object — so it survives as an orphan
+      process.kill(server.pid!, 'SIGKILL')
+      await new Promise((r) => setTimeout(r, 2000))
+
+      expect(isRunning(server.pid!)).toBe(false)
+      expect(isRunning(workerPid)).toBe(true)
+      // (afterEach reaps the orphaned worker)
+    },
+    15000
+  )
+
+  test.skipIf(process.platform === 'win32')(
+    'killProcessTree reaps an in-group worker (POSIX group-kill)',
+    async () => {
+      const { server, workerPid } = await spawnTree(false)
+      expect(server.pid).toBeTruthy()
+      expect(isRunning(server.pid!)).toBe(true)
+      expect(isRunning(workerPid)).toBe(true)
+
+      killProcessTree(server.pid)
+      await new Promise((r) => setTimeout(r, 2000))
+
+      expect(isRunning(server.pid!)).toBe(false)
+      expect(isRunning(workerPid)).toBe(false)
+    },
+    15000
+  )
+
+  test.skipIf(process.platform === 'win32')(
+    'a bare single-process kill orphans an in-group worker (POSIX, why tree-kill is needed)',
+    async () => {
+      const { server, workerPid } = await spawnTree(false)
+      expect(isRunning(workerPid)).toBe(true)
+
+      // signalling only the leader's PID leaves the rest of the group running
+      process.kill(server.pid!, 'SIGKILL')
+      await new Promise((r) => setTimeout(r, 2000))
+
+      expect(isRunning(server.pid!)).toBe(false)
+      expect(isRunning(workerPid)).toBe(true)
+      // (afterEach reaps the orphaned worker)
+    },
+    15000
+  )
+})

tests/test/tests/process-tree.ts

@@ -0,0 +1,55 @@
+import { spawn } from 'node:child_process'
+
+/**
+ * Tree-kill a spawned dev server together with the worker processes it forked,
+ * cross-platform. Shared by the spawn-based tests in this directory so they all
+ * clean up the same (correct) way — mirrors `killProcessTree` in
+ * packages/test/src/setup.ts.
+ *
+ * POSIX: signal the whole process group via the negative PID. This requires the
+ * server to have been spawned with `detached: true` so it leads its own group;
+ * the workers it forks inherit that group and are signalled too. If the pid is
+ * not a group leader the negative-pid call throws and we fall back to signalling
+ * the single process. Pure Node — no shell-out.
+ *
+ * Windows: there is no process-group kill (`process.kill(-pid)` throws with
+ * ESRCH), and `process.kill(pid)` maps to TerminateProcess, which ends only the
+ * root — a worker that broke away from libuv's job object would be orphaned.
+ * `taskkill /F /T` walks the PID tree and ends those workers too. (Node has no
+ * built-in tree-kill, so this one shell-out is unavoidable for a robust result.)
+ */
+export function killProcessTree(pid: number | undefined): void {
+  if (!pid) return
+
+  if (process.platform === 'win32') {
+    try {
+      spawn('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore' })
+    } catch {
+      // process already gone — fine
+    }
+    return
+  }
+
+  // POSIX: graceful group SIGTERM, then a group SIGKILL fallback. The inner
+  // fallbacks signal the single process when the pid is not a group leader.
+  try {
+    process.kill(-pid, 'SIGTERM')
+  } catch {
+    try {
+      process.kill(pid, 'SIGTERM')
+    } catch {
+      // already gone
+    }
+  }
+  setTimeout(() => {
+    try {
+      process.kill(-pid, 'SIGKILL')
+    } catch {
+      try {
+        process.kill(pid, 'SIGKILL')
+      } catch {
+        // already gone
+      }
+    }
+  }, 1000)
+}