@angular/build:unit-test vitest executor hangs indefinitely — uses close() instead of exit()

[scottcurrie]

Which @angular/* package(s) are the source of the bug?

@angular/build

Is this a regression?

No — the vitest runner has always used close() since it was introduced.

Description

When running tests with the @angular/build:unit-test builder using the vitest runner in non-watch mode, the process hangs indefinitely after all tests complete and results are printed. This happens because the builder calls vitest.close() which has no teardown timeout, while the vitest CLI calls vitest.exit() which has a safety-net setTimeout → process.exit().

Root Cause

The vitest CLI (vitest run) handles shutdown like this (node_modules/vitest/dist/chunks/cac.CWGDZnXT.js:2317):

const ctx = await startVitest(mode, cliFilters, options);
if (!ctx.shouldKeepServer()) await ctx.exit(); // ← has teardownTimeout safety net

ctx.exit() sets an unref'd setTimeout(() => process.exit(), config.teardownTimeout) before calling close(). If pool workers fail to shut down, process.exit() fires after 10s (default teardownTimeout).

The Angular builder's VitestExecutor (executor.js:189) uses close() directly:

async [Symbol.asyncDispose]() {
    await this.vitest?.close();
}

Additionally, startVitest() itself calls ctx.close() in its finally block (cli-api.DuT9iuvY.js:14400-14402):

finally {
    if (!ctx?.shouldKeepServer()) {
        await ctx.close();  // hangs here — no timeout
    }
}

close() awaits pool.close() with no timeout. If any vitest pool worker doesn't respond to the "stop" message within 60s (STOP_TIMEOUT, hardcoded in vitest), PoolRunner.stop() throws but never calls this.worker.stop() to kill the process. The zombie workers' IPC channels (ref=true) keep the Node.js event loop alive indefinitely.

This is a known class of bugs in Vitest 4's pool implementation (vitest-dev/vitest#8766, vitest-dev/vitest#9494, vitest-dev/vitest#8861).

Suggested Fix

After startVitest() returns, call ctx.exit() for non-watch mode, matching what the vitest CLI does:

const ctx = await startVitest('test', undefined, vitestConfig, vitestServerConfig);
if (!ctx?.config?.watch) {
    await ctx.exit();
}

Or add an equivalent teardown timeout in the [Symbol.asyncDispose]() method.

Please provide a link to a minimal reproduction of the bug

No external reproduction — the issue is observable from source code analysis:

• executor.js:189 calls this.vitest?.close() (no timeout)
• executor.js:314 calls startVitest() which calls ctx.close() in its finally block (no timeout)
• Vitest CLI (cac.CWGDZnXT.js:2317) calls ctx.exit() (has teardownTimeout safety net)

Reproducible with any large Angular project (232+ test files) on Windows using @angular/build:unit-test with vitest runner and --no-watch.

Please provide the exception or error you saw

No error. The process completes all tests, prints the summary, then hangs indefinitely. process._getActiveHandles() shows 4 ChildProcess + 12 Socket handles from vitest forks pool workers that were never killed.

Please provide the environment you discovered this bug in

@angular/build: 21.2.2
vitest: 4.1.0
Node.js: 22.14.0
OS: Windows 11 Pro 10.0.26200

Anything else?

Workaround: Add a globalSetup teardown in vitest-base.config.ts that mirrors ctx.exit()'s safety net:

// vitest-global-teardown.ts
export async function teardown() {
  setTimeout(() => process.exit(process.exitCode ?? 0), 10_000).unref();
}

The _teardownGlobalSetup() runs inside Vitest.close() before pool.close(), so the timer fires during the pool hang.

[scottcurrie]

Additional findings

Also reproduces on Linux

The original report was on Windows. We've since confirmed the same hang on Ubuntu 24.04 in GitHub Actions CI (ubuntu-latest, Node.js 22.x). The CI runner's orphan cleanup shows both vitest workers and esbuild services lingering:

Terminate orphan process: pid (2297) (npm run test-cc)
Terminate orphan process: pid (2309) (ng run BimlFlex:test --no-watch --coverage)
Terminate orphan process: pid (2333) (esbuild)
Terminate orphan process: pid (2350) (esbuild)
Terminate orphan process: pid (2358) (node)

On Linux, vitest workers may exit cleanly but the esbuild service processes (spawned by the Angular builder) also keep the event loop alive. The ctx.exit() safety net would handle both cases since it calls process.exit() after teardownTimeout.

Workaround correction

The globalSetup teardown suggested in the original report does not work — the Angular builder's config plugin places user test config inside a projects array, and project-level globalSetup teardown doesn't fire at the right point in Vitest.close().

The configureVitest Vite plugin hook also doesn't fire for user plugins added via vitest-base.config.ts (they end up in project-level plugins after the builder's extraction).

Our current workaround is a Node.js --require preload script that monitors process._getActiveHandles() and kills/unrefs zombie ChildProcess/Socket handles after detecting 60s of stdout silence (vitest prints results continuously during active test runs, so silence = close() is hanging). This handles both zombie vitest forks (Windows) and lingering esbuild services (Linux).

Timing clarification

Vitest.close() does eventually return after ~60s (the hardcoded STOP_TIMEOUT for each worker). The process then stays alive indefinitely because zombie workers' IPC channels and esbuild's stdio pipes are ref'd handles on the Node.js event loop. The suggested fix (ctx.exit() with its teardownTimeout → process.exit() safety net) would catch this.