fix(pool): improve error message when worker exits unexpectedly by filmaj · Pull Request #10587 · vitest-dev/vitest

filmaj · 2026-06-12T18:47:00Z

Description

In a large project leveraging vitest, with heavy integration test setup routines involved, we noticed sometimes the test worker threads would 'unexpectedly exit' but without much information. Poking around the code, it seems like the child-process-based pool workers expose code and signal to exit events. Worker threads expose exit codes, though no signal.

However, vitest doesn't expose that information in the case that forks or worker thread-based pool workers exit unexpectedly. This information was helpful for us to diagnose at least one test 'flakiness' issue we encountered (SIGSEGV when native extensions were dipping into global shared memory spaces).

This PR is a conversation starting point as I'm a first-timer contributor to vitest! I am missing a few things in the checklist below and am open to any feedback on how to make this PR easier to review / accept.

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
- Given the size of the patch, and that it was referenced as a monkey-patch in another raised issue (meaning this technique was useful to at least one other person), I did not raise an issue first, but happy to if that would be a better venue to discuss this.
Ideally, include a test that fails without this PR but passes with it.
Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.
Please check Allow edits by maintainers to make review process faster. Note that this option is not available for repositories that are owned by Github organizations.

Tests

Run the tests with pnpm test:ci.
- I did, though I got a 'worker unexpectedly exited' error running this command on main - which is ironic given what this PR does!

Documentation

If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

AriPerkkio

Test case for this could be in

vitest/test/e2e/test/pool-worker-exit.test.ts

Lines 1 to 71 in 5b81a63

    
           import { runVitest, StableTestFileOrderSorter } from '#test-utils' 
        
           import { resolve } from 'pathe' 
        
           import { expect, test } from 'vitest' 
        
           import { readCoverageMap } from '../../coverage-test/utils' 
        
           test('worker death on a shared runner does not skip coverage finalization', async () => { 
        
             const root = './fixtures/pool-worker-exit' 
        
             const { buildTree } = await runVitest({ 
        
               root, 
        
               pool: 'forks', 
        
               // Disable isolation to make sure crashed worker doesn't hang whole test run 
        
               isolate: false, 
        
               maxWorkers: 2, 
        
               sequence: { sequencer: StableTestFileOrderSorter }, 
        
               include: [ 
        
                 '1-first.test.ts', 
        
                 '2-crash.test.ts', 
        
                 '3-crash.test.ts', 
        
                 '4-third.test.ts', 
        
               ], 
        
               reporters: 'default', 
        
               coverage: { 
        
                 enabled: true, 
        
                 provider: 'v8', 
        
                 reporter: ['json'], 
        
                 reportOnFailure: true, 
        
               }, 
        
             }) 
        
             expect(buildTree(t => ({ state: t.result().state }))).toMatchInlineSnapshot(` 
        
               { 
        
                 "1-first.test.ts": { 
        
                   "first test exercises src so it should appear in coverage": { 
        
                     "state": "passed", 
        
                   }, 
        
                 }, 
        
                 "2-crash.test.ts": { 
        
                   "the worker dies before sending testfileFinished": { 
        
                     "state": "pending", 
        
                   }, 
        
                 }, 
        
                 "3-crash.test.ts": { 
        
                   "the worker dies before sending testfileFinished": { 
        
                     "state": "pending", 
        
                   }, 
        
                 }, 
        
                 "4-third.test.ts": { 
        
                   "third test": { 
        
                     "state": "passed", 
        
                   }, 
        
                 }, 
        
               } 
        
             `) 
        
             // Crashing worker should not interfere with other test-run, coverage should be reported: 
        
             const coverageMap = await readCoverageMap(resolve(root, 'coverage/coverage-final.json')) 
        
             const fileCoverage = coverageMap.fileCoverageFor('<process-cwd>/fixtures/pool-worker-exit/src.ts') 
        
             expect(fileCoverage.toSummary().functions).toMatchInlineSnapshot(` 
        
               { 
        
                 "covered": 1, 
        
                 "pct": 50, 
        
                 "skipped": 0, 
        
                 "total": 2, 
        
               } 
        
             `) 
        
           })

... where stderr (or buildTree or was it buildError?) is asserted to contain the signals and exit code.

filmaj · 2026-06-13T13:07:17Z

Thanks for the feedback and guidance @AriPerkkio! I have integrated your optional-code suggestion and was able to add a test to the test file you pointed to - very helpful, thanks. I validated at least this particular pool-worker-exit.test.ts passes locally without issue. I added a new test fixture file to forcibly process.exit the test with a large code to be able to assert on it, and changed an existing crash-test fixture file's signal to kill itself with SIGINT to assert on that as well. Let me know what you think.

netlify · 2026-06-15T13:37:52Z

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`b8cbc36`
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/6a391f37d7bc6c0008540cab
😎 Deploy Preview	https://deploy-preview-10587--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

…h multiple arguments

…of the crash tests to use SIGINT instead of SIGKILL, assert on stderr contents to check exit code and signal on worker death

AriPerkkio

Overall looks good, one small additional improvement to make the error more detailed.

…uring worker death

AriPerkkio

Looks good, thanks! 💯

filmaj commented Jun 12, 2026

View reviewed changes

Comment thread test/coverage-test/fixtures/src/query-param-transformed.ts Outdated

filmaj commented Jun 12, 2026

View reviewed changes

Comment thread packages/vitest/src/node/pools/types.ts

AriPerkkio reviewed Jun 13, 2026

View reviewed changes

Comment thread packages/vitest/src/node/pools/poolRunner.ts Outdated

AriPerkkio requested changes Jun 13, 2026

View reviewed changes

AriPerkkio changed the title ~~fix: expose process exit code and signal in unexpected worker exit error~~ fix(pool): expose exit code and signal in unexpected worker exit error Jun 13, 2026

filmaj requested a review from AriPerkkio June 13, 2026 13:07

filmaj added 5 commits June 16, 2026 07:53

chore: raise process exit code and signal during emitUnexpectedExit

bb44bee

expand type of event handlers in pool runner to accomodate events wit…

9f0592e

…h multiple arguments

undo change added somehow?

7cd8204

slightly more readable code and signal on unexpected exit, tweak one …

faefbf9

…of the crash tests to use SIGINT instead of SIGKILL, assert on stderr contents to check exit code and signal on worker death

update comment

cbac567

filmaj force-pushed the raise-code-signal branch from aa09561 to cbac567 Compare June 16, 2026 11:53

AriPerkkio requested changes Jun 17, 2026

View reviewed changes

Comment thread test/e2e/test/pool-worker-exit.test.ts Outdated

fix: raise which test file(s) are being executed in a worker thread d…

24040bf

…uring worker death

filmaj requested a review from AriPerkkio June 17, 2026 15:04

AriPerkkio reviewed Jun 22, 2026

View reviewed changes

Comment thread test/e2e/fixtures/pool-worker-exit/5-exit.test.ts Outdated

test: prevent calling Vitest's overriden process.exit

59389ef

AriPerkkio force-pushed the raise-code-signal branch from eefba19 to 6c76bb0 Compare June 22, 2026 11:05

test: verify stderr fully

b946a3e

AriPerkkio force-pushed the raise-code-signal branch from 6c76bb0 to b946a3e Compare June 22, 2026 11:07

AriPerkkio changed the title ~~fix(pool): expose exit code and signal in unexpected worker exit error~~ fix(pool): improve error message when worker exits unexpectedly Jun 22, 2026

AriPerkkio added 2 commits June 22, 2026 14:40

test: windows paths

c940d20

Merge branch 'main' into raise-code-signal

b8cbc36

AriPerkkio approved these changes Jun 22, 2026

View reviewed changes

AriPerkkio merged commit 76139c5 into vitest-dev:main Jun 22, 2026
14 of 18 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(pool): improve error message when worker exits unexpectedly#10587

fix(pool): improve error message when worker exits unexpectedly#10587
AriPerkkio merged 10 commits into
vitest-dev:mainfrom
filmaj:raise-code-signal

filmaj commented Jun 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AriPerkkio left a comment

Uh oh!

filmaj commented Jun 13, 2026

Uh oh!

netlify Bot commented Jun 15, 2026 •

edited

Loading

Uh oh!

AriPerkkio left a comment

Uh oh!

Uh oh!

Uh oh!

AriPerkkio left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	import { runVitest, StableTestFileOrderSorter } from '#test-utils'
	import { resolve } from 'pathe'
	import { expect, test } from 'vitest'
	import { readCoverageMap } from '../../coverage-test/utils'

	test('worker death on a shared runner does not skip coverage finalization', async () => {
	const root = './fixtures/pool-worker-exit'

	const { buildTree } = await runVitest({
	root,
	pool: 'forks',

	// Disable isolation to make sure crashed worker doesn't hang whole test run
	isolate: false,
	maxWorkers: 2,

	sequence: { sequencer: StableTestFileOrderSorter },
	include: [
	'1-first.test.ts',
	'2-crash.test.ts',
	'3-crash.test.ts',
	'4-third.test.ts',
	],

	reporters: 'default',
	coverage: {
	enabled: true,
	provider: 'v8',
	reporter: ['json'],
	reportOnFailure: true,
	},
	})

	expect(buildTree(t => ({ state: t.result().state }))).toMatchInlineSnapshot(`
	{
	"1-first.test.ts": {
	"first test exercises src so it should appear in coverage": {
	"state": "passed",
	},
	},
	"2-crash.test.ts": {
	"the worker dies before sending testfileFinished": {
	"state": "pending",
	},
	},
	"3-crash.test.ts": {
	"the worker dies before sending testfileFinished": {
	"state": "pending",
	},
	},
	"4-third.test.ts": {
	"third test": {
	"state": "passed",
	},
	},
	}
	`)

	// Crashing worker should not interfere with other test-run, coverage should be reported:
	const coverageMap = await readCoverageMap(resolve(root, 'coverage/coverage-final.json'))
	const fileCoverage = coverageMap.fileCoverageFor('<process-cwd>/fixtures/pool-worker-exit/src.ts')

	expect(fileCoverage.toSummary().functions).toMatchInlineSnapshot(`
	{
	"covered": 1,
	"pct": 50,
	"skipped": 0,
	"total": 2,
	}
	`)
	})

Uh oh!

Uh oh!

Conversation

filmaj commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Documentation

Changesets

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AriPerkkio left a comment

Choose a reason for hiding this comment

Uh oh!

filmaj commented Jun 13, 2026

Uh oh!

netlify Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vitest-dev ready!

Uh oh!

AriPerkkio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

AriPerkkio left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

filmaj commented Jun 12, 2026 •

edited

Loading

netlify Bot commented Jun 15, 2026 •

edited

Loading