Description

Introduces two new configuration options: pool and poolOptions. In #3925 configuring pools became too complex: #3925 (comment). This PR opens up easier API for such cases. Most users won't need these so good defaults are available as before.

In future we might open up an API for custom pools. This PR should have compatible API for such case.

Pool

Select pool which use to run tests in. Available values are 'threads'|'forks'|'vmThreads'. Defaults to 'threads'.

• Should 'forks' be 'child_process' instead? Or 'processes' or 'subprocesses'?
• I think after feat!: support multiple parallel child_process #3925 we can create vmForks quite easily

Pool Options

Specify options for each pool. API shape is similar as environment + environmentOptions.

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        isolate: true, // Default value
        maxThreads: 2,
        minThreads: 1,
        singleThread: false,
        useAtomics: true,
      },
      forks: {
        isolate: true,
        singleFork: false,
        minForks: 1, // Requires #3925
        maxForks: 2, // Requires #3925
      },
      vmThreads: {
        memoryLimit: "2GB",
        minThreads: 1,
        maxThreads: 2,
        singleThread: false,
        useAtomics: true,
      },
    }
  }
});

BREAKING CHANGES

• In earlier versions of Vitest --no-threads ran tests in a single child_process without isolating test context. Equivalent option is now --pool forks --poolOptions.forks.isolate false. See feat!: support multiple parallel child_process #3925 for more information about new child_process usage.
• --threads is now --pool=threads
• --no-threads is now --pool=forks
• --single-thread is now --poolOptions.threads.singleThread
• --experimental-vm-threads is now --pool=vmThreads
• --experimental-vm-worker-memory-limit is now --poolOptions.vmThreads.memoryLimit
• --isolate is now --poolOptions.<pool-name>.isolate and browser.isolate
• test.maxThreads is now test.poolOptions.<pool-name>.maxThreads
• test.minThreads is now test.poolOptions.<pool-name>.minThreads
• test.useAtomics is now test.poolOptions.<pool-name>.useAtomics
• test.poolMatchGlobs.child_process is now test.poolMatchGlobs.forks
• test.poolMatchGlobs.experimentalVmThreads is now test.poolMatchGlobs.vmThreads

Migration examples

{
  scripts: {
-    "test": "vitest --no-threads"
// For identical behaviour:
+    "test": "vitest --pool forks --poolOptions.forks.singleFork"
// Or multi parallel forks:
+    "test": "vitest --pool forks"

  }
}

{
  scripts: {
-    "test": "vitest --experimental-vm-threads"
+    "test": "vitest --pool vmThreads"
  }
}

{
  scripts: {
-    "test": "vitest --isolate false"
+    "test": "vitest --poolOptions.threads.isolate false"
  }
}

{
  scripts: {
-    "test": "vitest --no-threads --isolate false"
+    "test": "vitest --pool forks --poolOptions.forks.isolate false"
  }
}

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.
• 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.

Tests

• Run the tests with pnpm test:ci.

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:.