Custom Pool
WARNING
This is an advanced and very low-level API. If you just want to run tests, you probably don't need this. It is primarily used by library authors.
Vitest runs tests in pools. By default, there are several pools:
threads
to run tests usingnode:worker_threads
(isolation is provided with a new worker context)forks
to run tests usingnode:child_process
(isolation is provided with a newchild_process.fork
process)vmThreads
to run tests usingnode:worker_threads
(but isolation is provided withvm
module instead of a new worker context)browser
to run tests using browser providerstypescript
to run typechecking on tests
You can provide your own pool by specifying a file path:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
// will run every file with a custom pool by default
pool: './my-custom-pool.ts',
// you can provide options using `poolOptions` object
poolOptions: {
myCustomPool: {
customProperty: true,
},
},
},
})
If you need to run tests in different pools, use the workspace feature:
export default defineConfig({
test: {
workspace: [
{
extends: true,
test: {
pool: 'threads',
},
},
],
},
})
INFO
The workspace
field was introduced in Vitest 3. To define a workspace in Vitest 2, create a separate vitest.workspace.ts
file.
API
The file specified in pool
option should export a function (can be async) that accepts Vitest
interface as its first option. This function needs to return an object matching ProcessPool
interface:
import type { ProcessPool, TestSpecification } from 'vitest/node'
export interface ProcessPool {
name: string
runTests: (files: TestSpecification[], invalidates?: string[]) => Promise<void>
collectTests: (files: TestSpecification[], invalidates?: string[]) => Promise<void>
close?: () => Promise<void>
}
The function is called only once (unless the server config was updated), and it's generally a good idea to initialize everything you need for tests inside that function and reuse it when runTests
is called.
Vitest calls runTest
when new tests are scheduled to run. It will not call it if files
is empty. The first argument is an array of TestSpecifications. Files are sorted using sequencer
before runTests
is called. It's possible (but unlikely) to have the same file twice, but it will always have a different project - this is implemented via vitest.workspace.ts
configuration.
Vitest will wait until runTests
is executed before finishing a run (i.e., it will emit onFinished
only after runTests
is resolved).
If you are using a custom pool, you will have to provide test files and their results yourself - you can reference vitest.state
for that (most important are collectFiles
and updateTasks
). Vitest uses startTests
function from @vitest/runner
package to do that.
Vitest will call collectTests
if vitest.collect
is called or vitest list
is invoked via a CLI command. It works the same way as runTests
, but you don't have to run test callbacks, only report their tasks by calling vitest.state.collectFiles(files)
.
To communicate between different processes, you can create methods object using createMethodsRPC
from vitest/node
, and use any form of communication that you prefer. For example, to use WebSockets with birpc
you can write something like this:
import { createBirpc } from 'birpc'
import { parse, stringify } from 'flatted'
import { createMethodsRPC, TestProject } from 'vitest/node'
function createRpc(project: TestProject, wss: WebSocketServer) {
return createBirpc(
createMethodsRPC(project),
{
post: msg => wss.send(msg),
on: fn => wss.on('message', fn),
serialize: stringify,
deserialize: parse,
},
)
}
You can see a simple example of a pool made from scratch that doesn't run tests but marks them as collected in pool/custom-pool.ts.