maxWorkers run-mode default is documented as all available parallelism
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Newbie friendliness
- 89/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- typescript
- Domain
- documentation
Research direction
Read docs/config/maxworkers.md and compare its run-mode default description with the selector in packages/vitest/src/utils/workers.ts, which is called from packages/vitest/src/node/config/resolveConfig.ts. Update the documentation to describe the existing run-mode default accurately. Done when the documented behavior matches the resolver and distinguishes run mode from watch mode.
Written by the indexing model from the issue text.
Description
Documentation is
- Missing
- Outdated
- Confusing
- Not sure?
Explain in Detail
When maxWorkers is omitted, watch is disabled and no worker-count environment override is set, the 5.1.0 reference says the default uses all available parallelism. The released resolver instead leaves one core free, with a minimum of one worker. On Linux x64 with Node 24.22.3 and 2 available CPUs, both root and project resolve maxWorkers: 1. Explicit 2 and "100%" resolve 2. The pool uses that limit: with 8 available CPUs and 16 test files, vitest run ran at most 7 files at once, and --maxWorkers=100% ran 8.
The selector is called by resolveConfig. The same discrepancy reproduces on 5.0.5, and the page and selector are unchanged on main at 77a306757d6291a0ce6f6adb7142e39886f08ffe. The v4 page has the same sentence, and 4.1.12 also runs one fewer worker than available parallelism. This is separate from #11721's project watch-inheritance fix, merged in #11724.
To reproduce on a machine with more than one available CPU, save these files and run npm install --userconfig /dev/null --no-audit --no-fund, then node probe.mjs:
package.json:
{
"private": true,
"type": "module",
"dependencies": {
"vitest": "5.1.0",
"vite": "8.3.5"
}
}
probe.mjs:
import { availableParallelism } from 'node:os'
import { createRequire } from 'node:module'
import { createVitest } from 'vitest/node'
const require = createRequire(import.meta.url)
const parallelism = availableParallelism()
const versions = { node: process.version, vitest: require('vitest/package.json').version, vite: require('vite/package.json').version }
const cases = [
['run-default', { watch: false }],
['watch-default', { watch: true }],
['run-explicit', { watch: false, maxWorkers: parallelism }],
['run-percent', { watch: false, maxWorkers: '100%' }],
]
for (const [scenario, options] of cases) {
const ctx = await createVitest({ root: process.cwd(), config: false, ...options })
try {
const capture = config => ({ watch: config.watch, maxWorkers: config.maxWorkers === undefined ? 'undefined' : config.maxWorkers })
console.log(JSON.stringify({ scenario, versions, availableParallelism: parallelism, root: capture(ctx.config), projects: ctx.projects.map(project => ({ name: project.name, ...capture(project.config) })) }))
} finally {
await ctx.close()
}
}
This observes resolved configuration without running test files. Expected from the current reference: the run-default limit equals available parallelism. Actual: 2 available CPUs resolve to 1. Watch mode resolves to 1; the explicit and percentage controls each resolve to 2.
Your Suggestion for Changes
Correct the run-mode default description in docs/config/maxworkers.md to match the existing selector. No runtime policy change is needed.
Reproduction
No response
- Dominant language
- TypeScript
- Stars
- 17.4k
- Forks
- 2.2k
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 148
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from vitest-dev/vitest
-
docs: say that `vi.stubEnv` changes only `import.meta.env` in Browser ModeMay be free again A pull request for this issue was closed without being merged. Opendocumentation p1-chore
Difficulty 1/5 1-3 hours Newbie friendliness 82/100
vitest-dev/vitest#11971 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
vitest-dev/vitest#11941 · 2 comments ·
Maintainers usually reply within 1 day
-
A fixture named `task` breaks `expect` from the test contextMay be free again @hrishikeshpathak1009 claimed this 7 days ago, and no pull request is open. Openp2-edge-case
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
vitest-dev/vitest#11929 · 1 comment ·
Maintainers usually reply within 1 day
-
`%%` in a `test.each` / `describe.each` / `test.for` title consumes a parameterMay be free again A pull request for this issue was closed without being merged. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
vitest-dev/vitest#11913 · 1 comment ·
Maintainers usually reply within 1 day
-
Docs: importOriginal return type is missing PromisePossibly taken @ragib-mrb claimed this 6 days ago. Opendocumentation
Difficulty 1/5 Under an hour Newbie friendliness 94/100
vitest-dev/vitest#11894 · 1 comment ·
Maintainers usually reply within 1 day
All issues in vitest-dev/vitest
Similar issues
-
approved check:passed streams:remove
Difficulty 1/5 Under an hour Newbie friendliness 62/100
Maintainers usually reply within 1 day
-
Monthly Not a priority
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
Expensify/App#107229 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
GitTools/actions#2297 · 1 reaction ·
Maintainers usually reply within 1 day
-
bug
Difficulty 1/5 Under an hour Newbie friendliness 88/100
hiero-ledger/hiero-sdk-js#4793 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
microsoft/vscode-cosmosdb#3594 · 1 comment ·
Maintainers usually reply within 1 day