Skip to content
Vitest 3
Main Navigation Guide & APIConfigBrowser ModeAdvanced API
3.2.0
2.1.9
1.6.1
0.34.6

English

简体中文
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

English

简体中文
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

Appearance

Sidebar Navigation

API

Node API

Getting Started

Vitest

TestProject

TestSpecification

Test Task API

TestCase

TestSuite

TestModule

TestCollection

Plugin API

Runner API

Reporters API

Task Metadata

Guides

Running Tests

Extending Reporters

Custom Pool

Config Reference

Test API Reference

On this page

Advanced API ​

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 ​

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

You can start running Vitest tests using its Node API:

js
import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

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:

ts
import type { TestModule } from 'vitest/node';

const vitest = await startVitest('test');

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

TIP

The "Running Tests" guide has a usage example.

createVitest ​

ts
function createVitest(
  mode: VitestRunMode,
  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.

js
import { createVitest } from 'vitest/node';

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

TIP

The "Running Tests" guide has a usage example.

resolveConfig ​

ts
function resolveConfig(
  options: UserConfig = {},
  viteOverrides: ViteUserConfig = {}
): Promise<{
  vitestConfig: ResolvedConfig;
  viteConfig: ResolvedViteConfig;
}>;

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

ts
import { resolveConfig } from 'vitest/node';

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

INFO

Due to how Vite's createServer works, Vitest has to resolve the config during the plugin's configResolve hook. Therefore, this method is not actually used internally and is exposed exclusively as a public API.

If you pass down the config to the startVitest or createVitest APIs, Vitest will still resolve the config again.

WARNING

The resolveConfig doesn't resolve projects. To resolve projects configs, Vitest needs an established Vite server.

Also note that viteConfig.test will not be fully resolved. If you need Vitest config, use vitestConfig instead.

parseCLI ​

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

ts
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']
Pager
Next pageVitest

Released under the MIT License.

Copyright (c) 2021-Present Vitest Team

https://vitest.dev/advanced/

Released under the MIT License.

Copyright (c) 2021-Present Vitest Team