maxWorkers run-mode default is documented as all available parallelism

Open Beginner friendly
#12,015 4 comments 0 reactions 0 assignees View on GitHub

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

approved documentation
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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from vitest-dev/vitest

All issues in vitest-dev/vitest

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.