WebStorm 2026.2 Help

Vitest

WebStorm 集成了 Vitest ，一个 Vite原生的单元测试框架。 您可以从编辑器和通过运行/调试配置运行、调试、进行快照测试和测量测试覆盖率。

您可以重新运行失败的测试或打开 监视模式。 当您以此模式启动测试会话时，WebStorm 会监控项目源代码中的更改。 一旦对测试或其主体进行了任何更改，WebStorm 就会重新运行受影响的测试，您甚至不必重新启动运行/调试配置。

开始之前

  1. 请确保您的计算机上安装了 Node.js。

  2. 请确保在设置中启用了 Vite 插件。 按 Ctrl+Alt+S 打开设置，然后选择 插件。 点击 已安装 选项卡。 在搜索字段中，输入 Vite。 有关插件的更多信息，请参阅 插件管理。

安装 Vitest

  • 在命令行 shell 或嵌入式 终端 （Alt+F12 ）中输入：

    npm install --save-dev vitest

请在 Vitest 官方网站上的 入门 和 配置 Vitest 中了解更多信息。

运行并调试测试

在 WebStorm 中，您可以直接从编辑器中快速运行或调试单个 Vitest 测试，或者创建运行/调试配置以运行或调试某些或全部测试。

有关为 JavaScript 和 TypeScript 代码创建 Vitest 测试的更多信息，请参阅 Vitest 官方网站上的 Vitest 功能。

从编辑器运行或调试单个测试

  • 点击装订区域中的 运行图标 或 重新运行图标 ，并从列表中选择 运行 <test_name>。

    从编辑器运行一个 Vitest 测试

    在 运行 工具窗口中查看您的测试运行结果。 对于失败的测试，将显示错误发生的位置及其原因。

    错误详细信息

    您还可以在编辑器中查看测试是否通过或失败，由于装订区域的 测试状态图标 测试通过 和 测试失败。

    测试的装订区域图标

  • 要调试测试，请在其中 设置断点 ，在标记栏中点击 运行图标 或 重新运行图标 ，并在列表中选择 调试 <test_name>。

    从编辑器调试一个 Vitest 测试

    在 调试 工具窗口中， 检查挂起的测试并 逐步执行。

    一场 Vitest 调试会话

创建 Vitest 运行配置

  1. 打开 运行/调试配置对话框（运行 | 编辑配置 在主菜单中），点击 "添加"按钮 在左侧窗格中，然后从列表中选择 Vitest。 将打开 运行/调试配置：Vitest 对话框。

  2. 指定要使用的 Node.js 运行时。

    如果您选择 项目 别名， WebStorm 将自动使用在 JavaScript 运行时 页面上 Node.js 运行时 字段中的项目默认解释器。 在大多数情况下， WebStorm 会检测到项目的默认运行时，并自动填写该字段。

    您还可以选择其他已配置的本地或远程解释器，或点击 “浏览”按钮 并配置一个新的解释器。

    有关更多信息，请参阅 配置远程 Node.js 运行时、 配置本地 Node.js 运行时 和 在适用于 Linux 的 Windows 子系统上使用 Node.js。

    可选地指定要传递给 Node.js 的 Node.js 特定选项参数 和 环境变量。

    变量定义会显示在 环境变量 字段中，并以分号（; ）作为分隔符，例如：

    • NODE_PATH

      用于解析模块时要搜索的附加目录列表。 在 macOS 或 Linux 上，列表中的目录请使用冒号（: ）分隔，在 Windows 上请使用分号（; ）分隔。

    • NODE_MODULE_CONTEXTS

      设置为 1 可在各自的全局上下文中加载模块。

    • NODE_DISABLE_COLORS

      设置为 1 可在 REPL 中禁用颜色。

    环境变量

    或者，单击字段右侧的 浏览 编辑环境变量图标 ，然后在打开的 环境变量 对话框中配置变量列表：

    • 使用 、 、 和 按钮管理自定义变量列表。

    • 该对话框还会显示可用的系统环境变量列表。 如果不希望为当前配置使用系统环境变量，请取消选中 包括系统环境变量 复选框。

    • 准备就绪后，单击 确定。

  3. 指定 vitest 软件包的位置。

  4. 指定应用程序的工作目录。 默认情况下， 工作目录 字段显示项目根文件夹。 若要更改此预定义设置，请指定所需文件夹的路径。

  5. 指定要运行的测试。 这可以是一个特定的测试或套件，整个测试文件或包含测试文件的文件夹。

  6. 默认情况下， vite.config.ts 被使用。 如果 vite.config.ts 丢失，或您希望使用自定义配置，请指定 vitest.config.ts 进行使用。 请访问 Vitest 官方网站了解更多信息。

  7. 可选：

    在相关源码文件或测试中进行变更时自动配置重新运行测试。 要做到这一点，请在 --watch 标志中添加 Vitest 选项 字段。

    您还可以添加其他 Vitest 选项。 如需了解更多信息，请参考 Vitest official website。

  8. 可选：

    在 Node 选项 字段中，输入要传递给 Node.js 可执行文件的特定命令行选项。 可接受的选项是：

    • 使用 --require coffeescript/register ，运行期间可以将 CoffeeScript 文件即时编译为 JavaScript。

      此模式要求 register.js 文件（其属于 coffeescript 软件包）位于您的项目中。 因此，请确保您已按照 安装 CoffeeScript 编译器 中的说明在本地安装了 coffeescript 软件包。

    • 使用 --inspect 或 --inspect-brk 参数以支持 Chrome Debugging Protocol。

通过运行配置运行测试

  1. 从配置列表中选择 Vitest 运行/调试配置，然后在列表或工具栏中点击 运行图标。

    选择运行/调试配置

  2. 在 测试运行器 选项卡的 运行 工具窗口中监控测试执行并分析测试结果。 有关详细信息，请参考 探索测试结果。

    要调试测试， 设置断点 在必要的地方，选择运行/调试配置，然后点击 调试按钮。

    Vitest：测试结果

重新运行测试

您可以重新运行指定范围 Alt+Shift+R 中的所有测试，或仅重新运行失败的测试。

您还可以在 监视模式中启动测试。 在此模式下，WebStorm 监控保存的测试和相关测试对象的更改。 一旦检测到更改，WebStorm 将在不中断当前测试会话的情况下重新运行受影响的测试。

重新运行失败的测试

  • 点击 重新运行失败测试图标 测试结果工具栏。 WebStorm 将执行上一会话中失败的所有测试。

    Vitest：重新运行所有失败的测试

  • 若要重新运行某个特定失败的测试，请在其上下文菜单中选择 运行<test name>。

有关更多信息，请参阅 重新运行测试。

自动重新运行更新的测试（监视模式）

  1. 打开 Vitest 运行/调试配置，或 如上文所述创建一个新的配置。

  2. 在 Vitest 选项 字段中，输入 --watch。 在自动生成的 所有测试 配置中， --watch 选项已指定。

  3. 启动运行/调试配置。 如果某些测试失败，您可以在不中止测试会话的情况下更新它们或相关测试对象。 一旦您的更改被保存，WebStorm 会检测到它们并重新运行受影响的测试。

    在下面的示例中，第 29 行的 vue.test.ts 测试失败了。 使用 --watch 选项后，测试将在 vue.test.ts 将 '4 x 4 = 18' 替换为 '4 x 4 = 16' 并在 Ctrl+S 中保存更改后重新运行，或将焦点从 WebStorm 移开。

    在 --watch 模式下重新运行已更新的测试

快照测试

WebStorm 也支持 Vitest 快照测试。 当 WebStorm 第一次使用 toMatchSnapshot() 方法运行测试时，会创建一个快照文件，并且 快照 图标会出现在 toMatchSnapshot () 旁边的边距。 点击 快照图标 以打开生成的快照。

快照

监控代码覆盖率

使用 WebStorm，您还可以监控代码中有多少部分 已被 Vitest 测试覆盖。 WebStorm 会在专用的 覆盖 工具窗口中显示此统计信息，并在编辑器和 项目 工具窗口（Alt+1 ）中以可视化方式标记已覆盖和未覆盖的行。

Vitest 覆盖率报告

启用 Vitest 的代码覆盖率

安装 @vitest/coverage-v8 或 istanbul。 要做到这一点，请打开内置的 终端 Alt+F12 并输入以下任一内容：

  • npm install --save-dev @vitest/coverage-v8

  • npm install --save-dev @vitest/coverage-istanbul。

请访问 Vitest 官方网站上的 测试覆盖率了解详情。

运行测试并生成覆盖率报告

  1. 在编辑器中运行带覆盖率的特定套件或测试：在标记栏中点击 “运行”按钮 或 重新运行按钮 ，并在列表中选择 使用覆盖率运行 <test_name>。

    从编辑器运行 Vitest 测试并获取覆盖率

    或者：

    如上所述创建一个 Vitest 运行/调试配置。 从主工具栏的列表中选择 Vitest 运行/调试配置，然后点击列表右侧的 运行覆盖率图标 &#xa0;。

  2. 在 Coverage 工具窗口中监控代码覆盖率。 报告显示了多少文件经过了测试及其中已覆盖代码行的百分比。 从报告中，您可以跳转到文件并查看哪些行已覆盖（标记为绿色）以及哪些行未覆盖（标记为红色）：

故障排查

快速故障排除核对清单

  1. 打开命令行 shell 或嵌入式 终端 （Alt+F12 ），并检查 npm test 或 npx vitest run 是否执行成功。

  2. 在 Vitest 运行/调试配置中，确保 工作目录 字段中指定了项目根目录。

  3. 如果使用自定义 Vitest 配置，请确保 vitest .config.ts 或 vite.config.ts 配置文件的路径指定正确。

  4. 检查命令行选项。 调试时，将 --test-timeout=0 --no-file-parallelism 添加到 Vitest 选项 字段。

    命令行选项

  5. 如果使用 Docker 或 WSL，请检查路径映射和源代码映射。

    对于 Docker 调试，最常见的根本原因不是 Vitest 本身，而是本地环境与容器环境的差异。

以下是 Vitest-in-WebStorm 最常见的投诉。

WebStorm 未检测到 Vitest 测试

典型症状：

  • 测试旁未显示 运行测试 装订区域图标。

  • 显示 Test not found 错误。

  1. 确保项目中已安装 Vitest。 打开您的命令行 shell 或嵌入式 终端 （Alt+F12 ），然后输入 npm vitest --v。 应显示当前已安装的 Vitest 版本。 如果没有显示，请输入 npm install --save-dev vitest 以在当前项目中安装 Vitest。

  2. 确保测试文件名称遵循 Vitest 命名约定。

断点未命中

可能原因如下：

  • 源代码映射不匹配，这意味着 WebStorm 正在调试生成的 JavaScript，但源映射指向了错误的 TypeScript/TSX 源位置。

  • 工作目录错误。 因此，Vitest 可能找到错误的 package.json 、无法找到正确的 vitest.config.ts ，或错误解析别名。

  • 测试在 worker threads 中运行，所以可以并行运行多个测试文件。 这有助于提高速度，但调试时可能会出现问题。

  • Docker/WSL 路径不匹配，这意味着调试器看到的是一个文件路径，但 WebStorm 的源代码在另一个路径下。

  1. 将 --test-timeout=0 和 --no-file-parallelism Vitest 调试友好标志添加到 Vitest 选项 字段的 Vitest 运行/调试配置中。

    这样可以避免超时和并行测试执行问题，更多信息请参阅 Vitest 官方网站。

  2. 按下 Ctrl+Alt+S 打开设置，然后选择 构建、执行、部署 | Docker。 然后检查您的 Docker/WSL 映射，并与运行/调试配置中的路径映射进行比较。

测试在命令行 shell 中通过，但在通过 WebStorm UI 启动时失败

这可能是因为 WebStorm 中的测试环境与命令行 shell 中的不同。 WebStorm 可能以不同的设置启动 Vitest，导致测试行为不同。

  1. 打开 Vitest 运行/调试配置。

    • 请确认指定的 Node.js 运行时版本与命令行中使用的版本相同。

    • 请确保工作目录与命令行中使用的目录相同。

    • 如有必要，请比较环境变量。

    • 请确保使用相同的 Vitest 配置和 Vitest 选项。

  2. 从 WebStorm 运行测试时，不进行调试。 如果测试通过，则问题很可能与调试器有关。

  3. 如果需要调试测试，请在 Vitest 选项 字段中临时添加以下内容以禁用并行执行：

    --test-timeout=0--no-file-parallelism

  4. 如果使用 Docker 或 WSL，请验证 WebStorm 的路径映射是否与 Docker 或 WSL 路径一致。

路径别名失效

包含格式为 import { foo } from '@/foo' 的 import 语句的测试文件失败。

  1. 检查以下配置文件中的别名是否配置一致：

    • tsconfig.json

    • vite.config.ts

    • vitest.config.ts

  2. 尝试将测试配置放在 vite.config.ts 或 vitest.config.ts 中。 这样做可能有帮助，因为 Vitest 默认会读取 Vite 配置。

缺少 DOM API

错误示例：

  • document 未定义

  • window 未定义

  • HTMLElement 未定义

使用类似浏览器的测试环境。

  1. 安装 jsdome。 为此，打开命令行 shell 或嵌入式 终端 （Alt+F12 ），然后输入：

    npm install --d jsdom

  2. 打开 vitest.config.ts 配置文件，并在其中添加以下代码：

    import { defineConfig } from 'vitest/config' export default defineConfig({ test: { environment: 'jsdom' } })

缺少环境变量

确保前端风格的环境变量有 VITE_ 前缀，例如：

VITE_API_URL=http://localhost:3000

同样在您的代码中：

import.meta.env.VITE_API_URL

监视模式表现异常

在 Docker、WSL 或挂载卷下监视文件可能较为棘手。

在命令行 shell 或嵌入式 终端 （Alt+F12 ）中，输入 vitest run。

如果命令执行成功，问题很可能出在 watch 模式或文件系统通知中。

    2026年 7月 14日
    运行/调试配置：ProtractorTypeScript