前言¶
Vite 生态里，Vitest 已是常见的单元测试选择：与 Vite 共用配置与转换管道，启动和 watch 通常比传统 Jest 链路更轻。团队从 Jest 迁移时，最容易踩坑的是 mock 命名空间（jest.* 与 vi.*）、ESM 下的 vi.mock 提升，以及 vitest.config.ts 里 environment、globals 等字段该怎么配。
若把上述约定交给 AI 临时「猜」，往往会出现 jest.fn()、漏写 import { vi } from 'vitest'，或配置与项目实际目录不一致。vitest-skill 是 TestMu AI（原 LambdaTest）在 agent-skills 仓库中维护的 Agent Skill，面向 Cursor、Claude Code、GitHub Copilot、Gemini CLI 等编码助手，在用户提到 Vitest、vi.mock、vitest.config 等关键词时，引导生成符合 Vitest 习惯的 JavaScript/TypeScript 测试代码。
这是什么¶
vitest-skill 的定位是：在 AI 对话中生成 Vitest 单元测试与相关集成测试写法，强调 Jest 兼容 API、ESM 支持，以及与 Vite 同源的测试运行方式。Skill 元数据标明作者为 TestMu AI，版本 1.0，MIT 许可证，适用语言为 JavaScript 与 TypeScript，分类为 unit-testing。
官方 Skill 目录：https://github.com/LambdaTest/agent-skills/tree/main/vitest-skill
触发场景（来自 Skill 描述）包括用户提及「Vitest」「vi.mock」「vitest.config」「vi.fn」「Vite test」「vitest config」等。
与同仓库中的 Jest、Cypress 等 Skill 相比，vitest-skill 聚焦 Vite 项目内的 vi 命名空间、In-Source Testing、以及与 @testing-library/react 结合的组件测试模式，而不是浏览器 E2E 或纯 Jest 默认栈。
核心功能¶
以下内容均来自官方 Skill 文档与 Quick Reference，不展开未在资料中出现的能力。
基础测试结构¶
Skill 内置 describe / it / expect / beforeEach 等典型写法，并从 vitest 包显式导入，示例如下。
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { Calculator } from './calculator';
describe('Calculator', () => {
let calc: Calculator;
beforeEach(() => { calc = new Calculator(); });
it('adds two numbers', () => {
expect(calc.add(2, 3)).toBe(5);
});
it('throws on divide by zero', () => {
expect(() => calc.divide(10, 0)).toThrow();
});
});
Mock、Spy 与定时器（vi 而非 jest）¶
资料明确要求使用 vi.mock、vi.fn、vi.spyOn 以及 fake timers API，并在 Anti-Patterns 表中指出不应使用 jest.fn() / jest.mock()。
import { vi } from 'vitest';
vi.mock('./database', () => ({
getUser: vi.fn().mockResolvedValue({ name: 'Alice' }),
saveUser: vi.fn().mockResolvedValue(true),
}));
const mockFn = vi.fn();
mockFn.mockReturnValue(42);
mockFn.mockResolvedValue({ data: 'test' });
const spy = vi.spyOn(console, 'log').mockImplementation(() => {});
expect(spy).toHaveBeenCalledWith('message');
spy.mockRestore();
vi.useFakeTimers();
vi.advanceTimersByTime(1000);
vi.runAllTimers();
vi.useRealTimers();
In-Source Testing¶
支持在业务源码中通过 import.meta.vitest 编写同文件测试，需在 vitest.config 中配置 includeSource（见下文配置示例）。
Snapshot¶
包含 toMatchSnapshot 与 toMatchInlineSnapshot 示例。
React 组件测试¶
示例结合 @testing-library/react 的 render 与 screen，测试文件从 vitest 导入 describe / it / expect。
反模式对照¶
| 不推荐 | 推荐 | 说明 |
|---|---|---|
jest.fn() |
vi.fn() |
Vitest 使用 vi 命名空间 |
jest.mock() |
vi.mock() |
与 Jest 命名空间不同 |
| 无类型约束 | TypeScript + strict | Skill 侧强调 TS 优先 |
命令速查¶
| 任务 | 命令 |
|---|---|
| 单次运行 | npx vitest run |
| Watch（默认） | npx vitest |
| UI | npx vitest --ui |
| 覆盖率 | npx vitest --coverage |
| 指定文件 | npx vitest run src/math.test.ts |
| 按用例名过滤 | npx vitest run -t "adds" |
推荐 vitest.config.ts 片段¶
Skill 文档给出的生产向配置示例包含 globals、jsdom 环境、v8 覆盖率与 includeSource：
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
globals: true,
environment: 'jsdom',
coverage: { provider: 'v8', reporter: ['text', 'html'] },
include: ['src/**/*.{test,spec}.{js,ts,tsx}'],
includeSource: ['src/**/*.{js,ts}'],
},
});
深度参考 playbook¶
更长的模式（工作区配置、React Testing Library、表驱动 test.each、API/集成测试、GitHub Actions CI、调试清单等）在 Skill 仓库内的 reference/playbook.md，共 10 个章节；需要让 AI 展开某类场景时，可在对话中点名 playbook 中的主题。
安装与启用¶
vitest-skill 随 LambdaTest/agent-skills 发布。仓库 README 说明：需 Node.js 与 npm（建议最新稳定版）、可用的 AI 编码助手，以及 TestMu AI 账号的 username 与 access key（用于 agentskillsforall 相关流程）。
仓库级初始化（可选）¶
若本地已有 agent-skills 克隆，可先安装 CLI 依赖并注册技能源：
git clone https://github.com/LambdaTest/agent-skills && cd agent-skills
npx agentskillsforall add https://github.com/LambdaTest/agent-skills.git
凭证环境变量（macOS / Linux）：
export LT_USERNAME="YOUR_USERNAME"
export LT_ACCESS_KEY="YOUR_ACCESS_KEY"
Windows 使用 set LT_USERNAME=... 与 set LT_ACCESS_KEY=...（具体以官方文档为准）。
只安装 vitest-skill¶
npx agentskillsforall add https://github.com/LambdaTest/agent-skills.git --skill vitest-skill
查看该源下全部 Skill：
npx agentskillsforall list https://github.com/LambdaTest/agent-skills.git
Cursor、Claude Code、Copilot 等助手的具体「技能挂载路径」因产品版本而异；完整步骤见 TestMu AI Agent Skills 文档。安装完成后，在项目里用自然语言描述测试需求即可，例如要求为某个模块补充 Vitest 用例并带上 vi.mock。
典型用法¶
下面介绍几种与官方示例一致、可直接对照仓库核对的用法。
1、为纯函数或类写基础用例¶
说明被测模块路径与边界条件（异常、除零等），并明确要求使用 vitest 导入而非 jest。助手在 Skill 约束下应输出与上文 Calculator 示例同结构的文件。
2、为依赖外部模块的代码写 mock¶
在对话中给出被 mock 的模块路径与期望返回值，并提到 vi.mock 或 vi.fn。Skill 资料中的 database mock 与 spy 片段可作为预期形态。
3、React 组件¶
说明组件 props 与应出现在 DOM 中的文案，要求使用 @testing-library/react + Vitest。官方示例通过 screen.getByText 断言。
4、与配置联动¶
若项目使用 In-Source Testing，一并说明 vitest.config.ts 中 includeSource 与 import.meta.vitest 条件块，避免只生成测试逻辑却缺少配置。
5、本地执行验证¶
生成代码后，用 Skill Quick Reference 中的命令在本地验证，例如：
npx vitest run
npx vitest run -t "adds"
适用场景与注意¶
适合：
- Vite / Vitest 技术栈的前端或全栈 TypeScript 项目，需要 AI 生成或补全
*.test.ts/*.spec.tsx。 - 从 Jest 迁移、希望输出统一改为
vi.*API 的团队。 - 需要 mock 模块、fake timers、快照或 RTL 组件测试模板时，作为对话中的「规范锚点」。
注意：
- Skill 指导的是测试代码与配置模式，不替代你在本机安装
vitest、@vitejs/plugin-*、jsdom等依赖；版本需与项目package.json一致，资料未绑定具体 Vitest 版本号。 - Anti-Patterns 表仅覆盖最常见的
jest命名空间误用；第三方库若仍暴露 Jest 全局，需在项目层单独处理。 reference/playbook.md中的 CI、集成测试等属于扩展阅读，生成结果仍应经npx vitest run与 code review。- TestMu AI 云平台与 Tunnel 能力属于 agent-skills 仓库整体能力，vitest-skill 本身侧重本地 Vitest 代码生成；是否在云上执行需结合其他 Skill 或自有 CI。
结尾¶
vitest-skill 把 Vitest 的导入方式、vi mock、配置字段和常用 CLI 收敛成 Agent 可复用的说明，减少 AI 在 Vite 项目里写出 Jest 习惯代码的概率。若你已在用 Vitest 或正在配置 vitest.config，可将该 Skill 与仓库内 Jest、Cypress 等 Skill 对照选用。
官方地址：https://github.com/LambdaTest/agent-skills/tree/main/vitest-skill
