@gsc-basic/vitest-config

面向第三方项目的通用 Vitest 配置工具包。

设计目标

• 通过预设覆盖常见场景（node、web、vue）。
• 保持原生 Vitest 命令使用习惯（vitest、vitest run、vitest --ui）。

安装

在使用方项目中安装：

• @gsc-basic/vitest-config
• vite
• vitest

vitest-sonar-reporter 已由本包内置并在运行时自动解析，使用方项目无需重复声明该依赖。

如需 Vue 组件测试，请在使用方项目中显式安装 @vue/test-utils。

如需 UI 模式（vitest --ui），可直接使用，无需在使用方项目中额外安装 @vitest/ui。

覆盖率默认使用 V8 provider。需要对 Vue SFC 或复杂转换链路使用 Istanbul 插桩时，可在 coverage.provider 显式设置为 istanbul，无需在使用方项目重复安装 coverage provider。

API

createVitestConfig(options)

返回一个普通对象配置，适合在导出前继续加工或调试。

defineVitestConfig(options, overrides)

基于默认值生成配置，并通过 mergeConfig 合并 overrides。

mergeVitestConfig(baseConfig, overrideConfig)

对 Vitest mergeConfig 的轻量封装。

配置项设计

配置按职责拆分：

• preset: node | web | vue
• root: 根目录（用于路径解析）
• plugins: 框架插件开关（vue、vueJsx）
• resolve: 直接透传 Vitest/Vite 官方 resolve 配置
• css: 透传 Vite css 配置
• test: Vitest 运行时配置（environment、setupFiles、coverage、depsInline、ui、sonarReporter 等）

其中 test.sonarReporter 支持两种形式：

• true: 启用 SonarQube Generic Execution 报告，输出到默认路径 reports/vitest-sonar-report.xml
• 对象: 透传 outputFile、silent、onWritePath 进行细粒度配置

当前包开箱即用仅保证 node 与 happy-dom 两类测试环境，这也与内置预设和依赖保持一致。

预设说明

• node
  • environment: node
  • css transform: 关闭
  • vue 插件: 关闭
• web
  • environment: happy-dom
  • css transform: 开启
  • vue 插件: 关闭
• vue
  • environment: happy-dom
  • css transform: 开启
  • vue 插件: 开启

使用示例

Node 项目最小配置

import { defineVitestConfig } from '@gsc-basic/vitest-config';

export default defineVitestConfig({
  preset: 'node',
  test: {
    setupFiles: ['./test/setup.ts'],
  },
});

Web 项目

import { defineVitestConfig } from '@gsc-basic/vitest-config';

export default defineVitestConfig({
  preset: 'web',
  test: {
    coverage: true,
  },
});

Vue 项目

import path from 'node:path';
import { defineVitestConfig } from '@gsc-basic/vitest-config';

export default defineVitestConfig({
  preset: 'vue',
  resolve: {
    alias: {
      '@': path.resolve(process.cwd(), 'src'),
    },
  },
  test: {
    setupFiles: ['./test/setup.ts'],
    coverage: {
      include: ['src/**/*.{ts,tsx,js,jsx,vue}'],
    },
  },
});

Istanbul 覆盖率

V8 是默认 provider。若项目将未执行的 Vue SFC 纳入 coverage.include，且 V8 覆盖率重映射无法处理项目的转换链路，可切换到 Istanbul：

import { defineVitestConfig } from '@gsc-basic/vitest-config';

export default defineVitestConfig({
  preset: 'vue',
  test: {
    coverage: {
      provider: 'istanbul',
      include: ['src/**/*.{ts,tsx,js,jsx,vue}'],
    },
  },
});

SonarQube 测试执行报告

设置 test.sonarReporter 后，测试结果会生成 SonarQube Generic Execution XML；终端仍保留 Vitest 默认报告器输出。

在 pnpm 场景下，包内部会优先解析 reporter 的绝对路径，避免业务仓库出现 Failed to load custom Reporter from vitest-sonar-reporter。

import { defineVitestConfig } from '@gsc-basic/vitest-config';

export default defineVitestConfig({
  test: {
    sonarReporter: {
      outputFile: 'reports/sonar-report.xml',
      silent: true,
    },
    coverage: true,
  },
});

sonarReporter: true 使用默认输出路径 reports/vitest-sonar-report.xml。在 sonar-project.properties 中配置：

sonar.testExecutionReportPaths=reports/vitest-sonar-report.xml
sonar.javascript.lcov.reportPaths=coverage/lcov.info

最短迁移清单（从业务仓库迁移到本包）

1. 安装依赖：在业务仓库新增 @gsc-basic/vitest-config，并确保保留 vite、vitest。
2. 新建或改造 vitest.config.mjs：改为 import { defineVitestConfig } from '@gsc-basic/vitest-config'。
3. 选择预设：
   • 纯函数/Node 工具库选 node
   • 浏览器逻辑选 web
   • Vue 组件项目选 vue
4. 回填项目特有项：把原配置中的 setupFiles、coverage include、alias、css 预处理配置迁入新配置对象。
5. 清理重复配置：从业务仓库旧的 vite 配置链中移除 test 相关段，避免双配置。
6. 验证命令：依次执行 vitest、vitest run、vitest --ui（如使用 UI）。
7. 最后收敛依赖：
   • 若项目测试代码直接 import 了 @vue/test-utils，继续保留在业务仓库。

• 若项目使用 vitest --ui，无需在业务仓库重复声明 @vitest/ui。

命令使用

本包不替代 Vitest CLI，请在使用方项目保留原生命令：

• vitest
• vitest run
• vitest --ui

注意事项

• 测试代码中直接使用到的库，请在使用方项目显式声明（如 @vue/test-utils）。
• test.environment 当前仅建议使用 node 或 happy-dom，包本身未内置 jsdom、edge-runtime 相关支持。
• coverage.provider 支持 v8 与 istanbul，默认使用 v8。
• 如遇到历史项目本地仍报 reporter 加载错误，优先升级 @gsc-basic/vitest-config 到包含该修复的版本，而不是在业务仓库新增 vitest-sonar-reporter 直连依赖。