前言¶
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
