Getting Started advanced

WARNING

This guide lists advanced APIs to run tests via a Node.js script. If you just want to run tests, you probably don't need this. It is primarily used by library authors.

You can import any method from the vitest/node entry-point.

startVitest

function startVitest(
  cliFilters: string[] = [],
  options: CliOptions = {},
  viteOverrides?: ViteUserConfig,
  vitestOptions?: VitestOptions,
): Promise<Vitest>

You can start running Vitest tests using its Node API:

import { startVitest } from 'vitest/node'

const vitest = await startVitest()

await vitest.close()

startVitest function returns Vitest instance if tests can be started.

If watch mode is not enabled, Vitest will call close method automatically.

If watch mode is enabled and the terminal supports TTY, Vitest will register console shortcuts.

You can pass down a list of filters as a second argument. Vitest will run only tests that contain at least one of the passed-down strings in their file path.

Additionally, you can use the third argument to pass in CLI arguments, which will override any test config options. Alternatively, you can pass in the complete Vite config as the fourth argument, which will take precedence over any other user-defined options.

After running the tests, you can get the results from the state.getTestModules API:

import type { TestModule } from 'vitest/node'

const vitest = await startVitest()

console.log(vitest.state.getTestModules()) // [TestModule]

TIP

The "Running Tests" guide has a usage example.

createVitest

function createVitest(
  options: CliOptions,
  viteOverrides: ViteUserConfig = {},
  vitestOptions: VitestOptions = {},
): Promise<Vitest>

You can create Vitest instance by using createVitest function. It returns the same Vitest instance as startVitest, but it doesn't start tests and doesn't validate installed packages.

import { createVitest } from 'vitest/node'

const vitest = await createVitest('test', {
  watch: false,
})

TIP

The "Running Tests" guide has a usage example.

resolveConfig

function resolveConfig(
  options: UserConfig = {},
  viteOverrides: ViteUserConfig = {},
  harness?: PluginHarness,
): Promise<ResolvedViteConfig>

This method resolves the config with custom parameters, without creating a Vite server. If no parameters are given, the root will be process.cwd().

It returns the resolved Vite config. The fully resolved Vitest config, including every project, lives on its test property.

import { resolveConfig } from 'vitest/node'

const viteConfig = await resolveConfig({
  mode: 'custom',
  configFile: false,
  resolve: {
    conditions: ['custom']
  },
  test: {
    setupFiles: ['/my-setup-file.js'],
    pool: 'threads',
  },
})

viteConfig.test.pool // 'threads'

INFO

This is the same method Vitest uses internally to resolve the config before creating the server. If you pass the options down to startVitest or createVitest, Vitest resolves them again.

You can pass a shared PluginHarness as the third argument to reuse a logger and package installer across calls.

parseCLI

function parseCLI(argv: string | string[], config: CliParseOptions = {}): {
  filter: string[]
  options: CliOptions
}

You can use this method to parse CLI arguments. It accepts a string (where arguments are split by a single space) or a strings array of CLI arguments in the same format that Vitest CLI uses. It returns a filter and options that you can later pass down to createVitest or startVitest methods.

import { parseCLI } from 'vitest/node'

const result = parseCLI('vitest ./files.ts --coverage --browser=chrome')

result.options
// {
//   coverage: { enabled: true },
//   browser: { name: 'chrome', enabled: true }
// }

result.filter
// ['./files.ts']

createCLI

function createCLI(options?: CliParseOptions): CAC

Creates the Vitest command-line interface: a cac instance with all of Vitest's commands and options registered. parseCLI is built on top of it; use createCLI directly if you need the raw parser.

import { createCLI } from 'vitest/node'

const cli = createCLI()

PluginHarness

class PluginHarness {
  vitest?: Vitest
  version: string
  logger: Logger
  packageInstaller: VitestPackageInstaller
  getVitest(): Vitest
}

A container that Vitest passes to its internal plugins while the config is being resolved, before a Vitest instance exists. It holds the Logger, the package installer and the resolved version, and exposes the Vitest instance via getVitest() once it has been created (calling it earlier throws).

This is an advanced, plugin-facing API. You rarely construct one directly, but you can pass a shared instance to resolveConfig to reuse a logger and package installer.

Logger

class Logger {
  constructor(
    outputStream?: Writable,
    errorStream?: Writable,
  )
}

Vitest's terminal logger, exposed as vitest.logger. It handles formatted output, the error summary, the run banner and screen clearing. Construct one with custom stdout/stderr streams to capture or redirect Vitest's output when running it programmatically.

import { Logger } from 'vitest/node'

const logger = new Logger(process.stdout, process.stderr)