Vitest Migration & Config
Teaches the agent to migrate a Jest suite to Vitest — vi.mock and the globals shim, vitest.config workspaces/projects, coverage, browser mode, and Vitest v4 breaking changes.
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- Vitest Migration & Config
- tags
- [ "vitest", "migration", "jest", "vi-mock", "config", "coverage", "browser-mode", "projects" ]
- agents
- [ "claude-code", "cursor", "github-copilot", "windsurf", "codex", "aider", "continue", "cline", "zed", "bolt", "gemini-cli", "amp" ]
- author
- thetestingacademy
- domains
- [ "web", "api" ]
- license
- MIT
- version
- 1.0.0
- languages
- [ "typescript" ]
- frameworks
- [ "vitest", "jest" ]
- description
- Teaches the agent to migrate a Jest suite to Vitest — vi.mock and the globals shim, vitest.config workspaces/projects, coverage, browser mode, and Vitest v4 breaking changes.
- testingTypes
- [ "unit", "integration" ]
03 SKILL.md 正文
Vitest Migration & Config
This skill makes the agent migrate a Jest test suite to Vitest correctly and configure Vitest from scratch. Vitest is mostly Jest-compatible, but the differences bite: the vi namespace replaces jest, vi.mock hoisting needs vi.hoisted, ESM is first-class, and Vitest v4 removed workspace files in favor of inline projects. The agent should produce a config that runs fast, types cleanly, and reports coverage.
Use this skill when migrating from Jest, setting up vitest.config.ts, splitting unit vs browser tests, or resolving v4 upgrade breakage.
Core Principles
vireplacesjest.jest.fn->vi.fn,jest.mock->vi.mock,jest.spyOn->vi.spyOn,jest.useFakeTimers->vi.useFakeTimers. The assertion API (expect, matchers) is unchanged.- Mocks must reset explicitly. Set
test.clearMocks/restoreMocksin config or callvi.clearAllMocks()inbeforeEach— Vitest does not reset by default. vi.mockis hoisted; usevi.hoistedfor shared values. Variables the factory needs must be created viavi.hoisted(() => ...), since the factory runs before imports.- Decide on globals up front. Either enable
globals: true(Jest-like, no imports) or import{ describe, it, expect, vi }fromvitest. Pick one and addtypes: ['vitest/globals']if using globals. - v4 uses
projects, notworkspace. The standalonevitest.workspace.tsfile is removed; declare multiple environments via the inlineprojectsarray. - Browser mode replaces jsdom for real-DOM tests. Use
browser.instances(v4) to run component tests in a real browser engine via Playwright.
Workflow / Patterns
Pattern 1 — Mechanical Jest -> Vitest swap
Most test bodies migrate with a namespace rename. With globals: true, even the imports can stay as-is.
// Before (Jest):
// const fn = jest.fn();
// jest.spyOn(obj, 'method');
// jest.useFakeTimers();
// After (Vitest) — explicit imports (recommended, ESM-safe):
import { describe, it, expect, vi, beforeEach } from 'vitest';
describe('cart', () => {
beforeEach(() => vi.clearAllMocks());
it('adds an item', () => {
const onChange = vi.fn();
const cart = createCart(onChange);
cart.add({ sku: 'A1', qty: 2 });
expect(cart.total).toBe(2);
expect(onChange).toHaveBeenCalledWith(expect.objectContaining({ sku: 'A1' }));
});
});
Pattern 2 — vi.mock with vi.hoisted (the hoisting fix)
In Jest you prefix variables with mock. In Vitest, wrap them in vi.hoisted so they exist when the hoisted factory runs.
import { vi, test, expect, beforeEach } from 'vitest';
import { getUser } from './user-service';
import axios from 'axios';
// Create the spy in a hoisted block so the factory below can reference it.
const { mockGet } = vi.hoisted(() => ({ mockGet: vi.fn() }));
vi.mock('axios', () => ({
default: { get: mockGet }, // note: ESM default export shape
}));
beforeEach(() => vi.clearAllMocks());
test('resolves user from API', async () => {
mockGet.mockResolvedValue({ data: { id: 1, name: 'Ada' } });
const user = await getUser(1);
expect(user).toEqual({ id: 1, name: 'Ada' });
expect(axios.get).toHaveBeenCalledWith('/api/users/1');
});
Pattern 3 — Partial mock with importActual
The Vitest equivalent of jest.requireActual. The factory is async.
vi.mock('./config', async (importOriginal) => {
const actual = await importOriginal<typeof import('./config')>();
return {
...actual,
isProduction: vi.fn(() => false), // override one export, keep the rest real
};
});
Pattern 4 — A complete vitest.config.ts
Covers globals, environment, setup files, and coverage. This replaces jest.config.js.
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
globals: true, // Jest-like; otherwise import from 'vitest'
environment: 'node', // 'jsdom' for component DOM tests
setupFiles: ['./test/setup.ts'],
clearMocks: true, // reset vi.fn() call data before each test
restoreMocks: true, // restore spies to original impl
coverage: {
provider: 'v8', // fast, no instrumentation step
reporter: ['text', 'html', 'lcov'],
include: ['src/**/*.ts'],
exclude: ['src/**/*.d.ts', 'src/**/index.ts'],
thresholds: { lines: 80, functions: 80, branches: 75 },
},
},
});
If using globals: true, add to tsconfig.json:
{ "compilerOptions": { "types": ["vitest/globals"] } }
Pattern 5 — Multiple environments via projects (v4)
The v4 replacement for vitest.workspace.ts. Run Node unit tests and jsdom component tests in one command, each with its own config.
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
coverage: { provider: 'v8' },
projects: [
{
// Fast pure-logic tests in Node.
test: {
name: 'unit',
environment: 'node',
include: ['src/**/*.unit.test.ts'],
},
},
{
// DOM/component tests in jsdom.
test: {
name: 'dom',
environment: 'jsdom',
setupFiles: ['./test/dom-setup.ts'],
include: ['src/**/*.dom.test.ts'],
},
},
],
},
});
Pattern 6 — Browser mode (real engine, v4 instances)
For component tests that need a real browser. v4 replaced the singular browser.name with a browser.instances array.
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
browser: {
enabled: true,
provider: 'playwright',
headless: true,
instances: [
{ browser: 'chromium' },
{ browser: 'firefox' },
],
},
},
});
// component.browser.test.ts — runs in a real browser
import { render } from 'vitest-browser-react';
import { expect, test } from 'vitest';
import { Counter } from './Counter';
test('increments in a real browser', async () => {
const screen = render(<Counter />);
await screen.getByRole('button', { name: 'Increment' }).click();
await expect.element(screen.getByText('Count: 1')).toBeVisible();
});
Pattern 7 — package.json scripts and the runner
{
"scripts": {
"test": "vitest run",
"test:watch": "vitest",
"test:ui": "vitest --ui",
"coverage": "vitest run --coverage"
}
}
Best Practices
- Choose globals vs imports once and apply it suite-wide. If
globals: true, addtypes: ['vitest/globals']so TypeScript knowsexpect/vi. - Set
clearMocksandrestoreMocksin config — Vitest does not auto-reset, so omitting them recreates Jest's "leaky mock" bug. - Use
vi.hoistedfor any value avi.mockfactory references. This is the single most common migration failure. - Mock ESM default exports as
{ default: ... }in the factory — the shape differs from Jest's CJS interop. - Use the
v8coverage provider for speed; reserveistanbulonly if you need its specific report nuances. - Split slow DOM/browser tests into a separate
projectso the fast Node unit tests give quick feedback. - On v4 upgrade, replace
vitest.workspace.tswith inlineprojectsand convertbrowser.nametobrowser.instances.
Anti-Patterns
- Search-replacing
jest->viand assuming you're done. Mock hoisting and ESM default shapes still needvi.hoistedand{ default }. - Forgetting mocks reset because Vitest, unlike a default Jest setup, won't clear them for you.
- Referencing an outer variable in
vi.mockwithoutvi.hoisted. It isundefinedwhen the hoisted factory executes. - Keeping
vitest.workspace.tson v4. It is removed; the suite silently ignores it or errors. Useprojects. - Enabling
globals: truebut not addingvitest/globalstypes, producing a flood of "cannot find name 'expect'" TS errors. - Running everything in jsdom when most tests are pure logic — jsdom is slower and unnecessary. Default to
node. - Mixing
@jest/globalsimports into Vitest files — import fromvitestinstead.
When to Trigger This Skill
- "Migrate my Jest tests to Vitest"
- "Set up
vitest.config.ts" / "configure Vitest coverage" - "
vi.mockisn't working / variable is undefined in the factory" - "How do I mock a default ESM export in Vitest?"
- "Run component tests in a real browser with Vitest"
- "Vitest v4 broke my
workspace/browser.nameconfig" - "Split unit and DOM tests into projects"
- "Jest
requireActualequivalent in Vitest"
04 同仓库更多 Skills
nemoclaw-user-reference
Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. Use when looking up architecture, agent integration, plugin structure, or blueprint design. Trigger keywords - nemoclaw architecture, nemoclaw agent architecture, nemoclaw plugin blueprint structure, nemoclaw vs openshell, which cli, nemoclaw cli, openshell cli, sandbox commands, nemoclaw cli commands, nemoclaw command reference, nemoclaw network policy, sandbox egress control operator approval, nemoclaw troubleshooting, nemoclaw debug sandbox issues.
nemoclaw-user-overview
Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond the community sandbox, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. Use when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. Trigger keywords - nemoclaw ecosystem, openclaw openshell, nemoclaw vs openshell, sandboxed openclaw, how nemoclaw works, nemoclaw sandbox lifecycle blueprint, nemoclaw overview, openclaw always-on assistants, nvidia openshell, nvidia nemotron, nemoclaw release notes, nemoclaw changelog.
nemoclaw-user-monitor-sandbox
Inspects sandbox health, traces agent behavior, and diagnoses problems. Use when monitoring a running sandbox, debugging agent issues, or checking sandbox logs. Trigger keywords - monitor nemoclaw sandbox, debug nemoclaw agent issues.
nemoclaw-user-manage-sandboxes
Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence.
nemoclaw-user-manage-policy
Adds, removes, or modifies allowed endpoints in the sandbox policy. Use when customizing network policy, changing egress rules, or configuring sandbox endpoint access. Trigger keywords - customize nemoclaw network policy, sandbox egress policy configuration, nemoclaw integration policy examples, post-install policy setup, openshell approval workflow, policy preset, nemoclaw approve network requests, sandbox egress approval tui.
nemoclaw-user-get-started
Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. Trigger keywords - nemoclaw quickstart, install nemoclaw openclaw sandbox, nemohermes quickstart, hermes agent nemoclaw, run hermes openshell sandbox, nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop.