特性

• Vite 的配置、转换工具、解析器和插件支持
• 使用与你的应用相同的设置来运行测试！
• 智能且即时的观察模式，就像 Vite 中的 HMR 一样！
• 支持 Vue、React、Svelte、Lit、Marko 等的组件测试
• 开箱即用的 TypeScript 和 JSX 支持
• ESM 优先，支持顶层 await
• 通过 Tinypool 实现多线程 Worker
• 通过 Tinybench 支持基准测试
• 支持过滤测试套件和测试、设置超时及并发运行
• 支持工作区
• 兼容 Jest 的快照
• 内置 Chai 用于断言，并兼容 Jest expect API
• 内置 Tinyspy 用于模拟
• 使用 happy-dom 或 jsdom 模拟 DOM
• 浏览器模式用于在浏览器中运行组件测试
• 通过 v8 或 istanbul 进行代码覆盖率检测
• 类似 Rust 的内联测试
• 通过 expect-type 进行类型测试
• 支持测试分片

通过视频学习编写第一个测试

测试、开发和构建之间的共享配置

Vitest 沿用 Vite 的配置、转换工具、解析器和插件。这意味着你可以使用与你的应用相同的设置来运行测试。

了解更多请访问 配置 Vitest。

观察模式

$ vitest

当你修改源代码或测试文件时，Vitest 会智能搜索模块图并只重新运行相关的测试，就像 Vite 中的 HMR 一样！

在开发环境中，vitest 默认以 watch mode 启动；在 CI 环境中（当 process.env.CI 存在时），它会智能地以 run mode 启动。你可以使用 vitest watch 或 vitest run 来明确指定所需的模式。

使用 --standalone 标志启动 Vitest，使其在后台运行。它不会运行任何测试，直到相关文件发生变化。如果源代码发生变化，Vitest 不会运行测试，除非导入该源代码的测试已经运行。

开箱即用的常见 Web 惯用法

开箱即用地支持 ES Module / TypeScript / JSX / PostCSS。

线程

默认情况下，Vitest 通过 Tinypool（Piscina 的轻量级分支）使用 node:child_process 在多个进程中运行测试文件，从而允许测试并行运行。如果你想进一步提高测试套件的速度，可以考虑启用 --pool=threads 来使用 node:worker_threads 运行测试（注意：某些包可能不兼容此设置）。

要在单个线程或进程中运行测试，请参阅 poolOptions。

Vitest 还会隔离每个文件的环境，以确保一个文件中的环境变动不会影响其他文件。可以通过向 CLI 传递 --no-isolate 来禁用隔离（以牺牲正确性来换取执行性能）。

测试过滤

Vitest 提供了多种方法来缩小测试运行范围，从而加快测试速度，让你能够专注于开发。

了解更多关于 测试过滤。

并发运行测试

在连续的测试中使用 .concurrent，使它们并行启动。

import { describe, it } => 'vitest';

// 两个标记为 concurrent 的测试将并行执行
describe('suite', () => {
  it('serial test', async () => {
    /* ... */
  });
  it.concurrent('concurrent test 1', async ({ expect }) => {
    /* ... */
  });
  it.concurrent('concurrent test 2', async ({ expect }) => {
    /* ... */
  });
});

如果你在一个测试套件上使用 .concurrent，该套件中的所有测试都将并行执行。

import { describe, it } from 'vitest';

// 此套件中的所有测试都将并行启动
describe.concurrent('suite', () => {
  it('concurrent test 1', async ({ expect }) => {
    /* ... */
  });
  it('concurrent test 2', async ({ expect }) => {
    /* ... */
  });
  it.concurrent('concurrent test 3', async ({ expect }) => {
    /* ... */
  });
});

你还可以将 .skip、.only 和 .todo 与并发测试套件和测试一起使用。在 API 参考 中阅读更多内容。

WARNING

当运行并发测试时，快照和断言必须使用本地 测试上下文 的 expect，以确保检测到正确的测试。

快照

兼容 Jest 的快照支持。

import { expect, it } from 'vitest';

it('renders correctly', () => {
  const result = render();
  expect(result).toMatchSnapshot();
});

了解更多请见 快照。

Chai 和 Jest expect 兼容性

Chai 内置用于断言，并提供与 Jest expect 兼容的 API。

请注意，如果你正在使用添加匹配器的第三方库，将 test.globals 设置为 true 可提高兼容性。

Mocking

Tinyspy 内置用于模拟，并在 vi 对象上提供与 jest 兼容的 API。

import { expect, vi } from 'vitest';

const fn = vi.fn();

fn('hello', 1);

expect(vi.isMockFunction(fn)).toBe(true);
expect(fn.mock.calls[0]).toEqual(['hello', 1]);

fn.mockImplementation((arg: string) => arg);

fn('world', 2);

expect(fn.mock.results[1].value).toBe('world');

Vitest 支持 happy-dom 或 jsdom 来模拟 DOM 和浏览器 API。它们不包含在 Vitest 中，你需要单独安装它们：

$ npm i -D happy-dom
# 或者
$ npm i -D jsdom

之后，在你的配置文件中更改 environment 选项：

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'happy-dom', // 或者 'jsdom', 'node'
  },
});

了解更多请见 Mocking。

覆盖率

Vitest 支持通过 v8 进行原生代码覆盖率检测，以及通过 istanbul 进行插桩代码覆盖率检测。

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

了解更多请见 覆盖率。

源码内测试

Vitest 还提供了一种在源代码中与实现一起运行测试的方式，类似于 Rust 的模块测试。

这使得测试能够与实现共享相同的闭包，并且能够在不导出的情况下测试私有状态。同时，这也缩短了开发反馈周期。

// src/index.ts

// 实现
export function add(...args: number[]): number {
  return args.reduce((a, b) => a + b, 0);
}

// 源码内测试套件
if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest;
  it('add', () => {
    expect(add()).toBe(0);
    expect(add(1)).toBe(1);
    expect(add(1, 2, 3)).toBe(6);
  });
}

了解更多请见 源码内测试。

基准测试 实验性

你可以通过 [Tinybench] 使用 bench 函数运行基准测试，从而比较性能。

import { bench, describe } from 'vitest';

describe('sort', () => {
  bench('normal', () => {
    const x = [1, 5, 4, 2, 3];
    x.sort((a, b) => {
      return a - b;
    });
  });

  bench('reverse', () => {
    const x = [1, 5, 4, 2, 3];
    x.reverse().sort((a, b) => {
      return a - b;
    });
  });
});

类型测试 实验性

你可以编写测试以捕获类型回归。Vitest 附带 expect-type 包，旨在为你提供类似且易于理解的 API。

import { assertType, expectTypeOf, test } from 'vitest';
import { mount } from './mount.js';

test('my types work properly', () => {
  expectTypeOf(mount).toBeFunction();
  expectTypeOf(mount).parameter(0).toMatchTypeOf<{ name: string }>();

  // @ts-expect-error name 是一个字符串
  assertType(mount({ name: 42 }));
});

分片

使用 --shard 和 --reporter=blob 标志在不同机器上运行测试。 所有测试和覆盖率结果都可以在 CI 流程结束时使用 --merge-reports 命令进行合并：

vitest --shard=1/2 --reporter=blob
vitest --shard=2/2 --reporter=blob
vitest --merge-reports --reporter=junit --coverage.reporter=text

有关更多信息，请见 提高性能 | 分片。

环境变量

Vitest 专门自动加载 .env 文件中以 VITE_ 为前缀的环境变量，以保持与前端测试的兼容性，并遵循 Vite 的既定约定。若要加载 .env 文件中的所有环境变量，你可以使用从 vite 导入的 loadEnv 方法：

import { loadEnv } from 'vite';
import { defineConfig } from 'vitest/config';

export default defineConfig(({ mode }) => ({
  test: {
    // mode 定义了在存在多个 ".env.{mode}" 文件时，应选择哪一个
    env: loadEnv(mode, process.cwd(), ''),
  },
}));