Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Guides expert-level JavaScript and TypeScript testing: Vitest vs Jest decision tree, ESM mocking strategies, snapshot testing, coverage configuration, and test runner selection for modern projects.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
863 lines · 4,973 words
Use this skill when the user asks about:
Choosing between Vitest and Jest for a new or existing JavaScript/TypeScript project
Mocking ES modules (ESM) -- import statements, dynamic import()
Guides expert-level JavaScript and TypeScript testing: Vitest vs Jest decision tree, ESM mocking strategies, snapshot testing, coverage configuration, and test runner selection for modern projects.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the JavaScript Testing Patterns skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
What it covers
When to Use
Process
Output Format
Rules
Edge Cases
Example
Testing Configuration Decision
Configuration File
Domain Objects (for reference)
Test File
Coverage Thresholds
Mock Strategy Summary
Configuring test coverage thresholds, Istanbul/V8 providers, and coverage exclusion patterns
Setting up snapshot testing, inline snapshots, or snapshot update workflows
Testing TypeScript code including type-level assertions, declaration testing, or ts-jest vs native TypeScript support
Writing tests for async/await code, Promises, timers, or event emitters
Structuring test files, fixture patterns, and factory functions for complex domain objects
Migrating a Jest codebase to Vitest or upgrading a legacy Babel-Jest pipeline
Configuring test parallelism, worker threads, and test isolation modes
Writing parameterized/data-driven tests for multiple input/output scenarios
Do NOT use this skill when:
The user needs to initialize a Node.js project from scratch -- use nodejs-project-setup instead
The user is asking about general testing vocabulary (unit vs. integration vs. contract) without a JavaScript-specific angle -- use unit-testing-patterns
The user needs Playwright, Cypress, Puppeteer, or any browser-driven E2E testing -- use e2e-testing-patterns
The user is asking about React component testing with React Testing Library as the primary concern -- this skill covers the runner/mocking layer; a component-testing skill covers the rendering layer
The user is asking about API contract testing with Pact or schema validation tools
The user is asking about performance benchmarking frameworks (Vitest bench is adjacent but out of scope here)
Before recommending any tooling, gather the facts that determine every downstream decision.
Module system in use: Is the project CommonJS ("type": "module" absent or require() throughout), pure ESM ("type": "module" in package.json), or a hybrid with both? ESM-only projects rule out certain Jest configurations that rely on synchronous require() transforms.
Bundler/transpiler in use: Vite projects are almost always better served by Vitest. Webpack or esbuild projects work fine with either. Babel-only projects that rely on @babel/preset-env need extra care when switching runners.
TypeScript version and config strictness: TypeScript ≥ 5.0 with "moduleResolution": "bundler" or "node16" changes how test runners locate .d.ts files and how path aliases are resolved.
Existing test investment: Count existing test files. Fewer than 50 tests -- migrate fully. 50-500 tests -- run both runners in parallel during transition. 500+ tests -- migrate by package/folder boundary.
CI time budget: Ask about acceptable test suite wall-clock time. Vitest's thread-based parallelism with a shared worker pool typically runs 1.5x--3x faster than Jest on suites with many small tests. Jest's --runInBand is essential for database integration tests to avoid connection pool exhaustion.
Browser/JSDOM requirement: Tests needing browser globals (window, document, localStorage) require JSDOM or Happy-DOM environments. Configure this at the file level with @vitest-environment jsdom docblock or in vitest.config.ts per glob pattern.
This is the highest-leverage decision. It is difficult to reverse without migrating test files.
Start with Vitest if:
The project uses Vite as its build tool (Vitest reuses the same Vite config, plugin pipeline, and alias resolution -- zero duplication)
The project is pure ESM or TypeScript-first (Vitest handles both natively without Babel)
The team wants native TypeScript support without ts-jest or a Babel transform
Hot Module Replacement (HMR) in watch mode matters (Vitest re-runs only affected tests, not the full suite)
The project needs inline type-checking during tests using vitest --typecheck
Keep or adopt Jest if:
The project uses Create React App, Next.js (non-Turbopack), or NestJS -- all ship with first-class Jest support
The team has deep Jest institutional knowledge and a large snapshot corpus
The project requires jest-circus, jest-jasmine2, or custom runners for complex async scheduling
Third-party testing utilities (e.g., @testing-library/jest-dom, MSW v1 handlers) are tightly coupled to Jest's global injection model
The project targets Node.js ≤ 16 where Vitest's ESM requirements are harder to satisfy
During migration from Jest to Vitest:
Install vitest and add "test": "vitest" as a parallel script alongside "test:jest": "jest"
Vitest's API is Jest-compatible for describe, it, expect, beforeEach, afterEach, vi (equivalent to jest)
Replace jest.fn() with vi.fn(), jest.mock() with vi.mock(), jest.spyOn() with vi.spyOn()
A correct configuration prevents hours of debugging mysterious test failures.
Vitest configuration (vitest.config.ts):
import { defineConfig } from 'vitest/config'
import tsconfigPaths from 'vite-plugin-tsconfig-paths'
export default defineConfig({
plugins: [tsconfigPaths()],
test: {
globals: true, // expose describe/it/expect globally
environment: 'node', // or 'jsdom', 'happy-dom', 'edge-runtime'
include: ['src/**/*.{test,spec}.{ts,tsx}'],
exclude: ['node_modules', 'dist', 'e2e/**'],
setupFiles: ['./src/test/setup.ts'],
coverage: {
provider: 'v8', // faster; use 'istanbul' for branch accuracy
reporter: ['text', 'lcov', 'html'],
include: ['src/**/*.{ts,tsx}'],
exclude: ['src/**/*.d.ts', 'src/**/*.test.ts', 'src/test/**'],
thresholds: {
lines: 80,
branches: 75,
functions: 80,
statements: 80,
},
},
pool: 'threads', // 'forks' for Node.js child processes; use for native modules
poolOptions: {
threads: { singleThread: false },
},
},
})Jest configuration (jest.config.ts):
import type { Config } from 'jest'
const config: Config = {
preset: 'ts-jest/presets/default-esm', // for ESM TypeScript
testEnvironment: 'node',
extensionsToTreatAsEsm: ['.ts'],
moduleNameMapper: {
'^(\\.{1,2}/.*)\\.js$': '$1', // rewrite .js imports to resolve .ts files
'^@/(.*)$': '<rootDir>/src/$1',
},
transform: {
'^.+\\.tsx?$': ['ts-jest', { useESM: true }],
},
collectCoverageFrom: [
'src/**/*.{ts,tsx}',
'!src/**/*.d.ts',
'!src/**/*.test.{ts,tsx}',
'!src/test/**',
],
coverageThreshold: {
global: { lines: 80, branches: 75, functions: 80, statements: 80 },
},
testMatch: ['<rootDir>/src/**/*.test.{ts,tsx}'],
}
export default configKey settings with rationale:
pool: 'threads' in Vitest uses worker_threads -- fast but cannot load native .node addons. Use pool: 'forks' for projects with native modules (e.g., sharp, bcrypt, sqlite3).
environment: 'happy-dom' is 10-15x faster than jsdom for pure DOM manipulation tests. Use jsdom when tests rely on specific CSS layout behavior or MutationObserver edge cases.
setupFiles runs before each test file in isolation. globalSetup runs once before all tests and cannot access vi/jest globals -- use for starting database servers or mock HTTP servers.
ESM mocking is the most common source of confusion and broken tests. Apply these patterns precisely.
Static ESM mock with vi.mock() / jest.mock() (hoisted):
// Module mocking is HOISTED to the top of the file by the test runner,
// even if written later in the source. This is not normal JS execution order.
vi.mock('../services/emailService', () => ({
sendEmail: vi.fn().mockResolvedValue({ messageId: 'test-123' }),
validateAddress: vi.fn().mockReturnValue(true),
}))
// For modules with a default export:
vi.mock('../utils/logger', () => ({
default: {
info: vi.fn(),
error: vi.fn(),
warn: vi.fn(),
},
}))The ESM interop problem and solution:
Packages distributed as pure ESM (e.g., node-fetch v3, chalk v5, nanoid v4, execa v7) cannot be mocked with synchronous jest.mock() in standard Jest + Node.js because Jest's module registry uses CommonJS require() internally.
Solution 1 (preferred for Jest): Use jest-mock-extended or add "transformIgnorePatterns": [] and transform the ESM package through Babel. In jest.config.ts: transformIgnorePatterns: ['node_modules/(?!(node-fetch|chalk|nanoid)/)'].
Solution 2: Wrap the ESM dependency in a thin adapter module you own. Mock the adapter, not the package. This also decouples your code from the vendor API.
Solution 3 (Vitest): Vitest handles ESM natively -- vi.mock('node-fetch') works without transforms because Vitest operates on the same ESM graph as Vite.
Spying without replacing (non-destructive mocking):
import * as fs from 'node:fs/promises'
const readFileSpy = vi.spyOn(fs, 'readFile').mockResolvedValue('file content' as any)
afterEach(() => {
vi.restoreAllMocks() // resets ALL spies created with spyOn
})Manual mocks (__mocks__ directory):
Place a file at src/__mocks__/nodemailer.ts to auto-mock the nodemailer package for all tests in the project.
For relative imports, the __mocks__ directory must be adjacent to the module being mocked.
Call vi.mock('nodemailer') or jest.mock('nodemailer') in the test file to activate the manual mock -- it does not activate automatically for non-node_modules packages.
Timer mocking:
beforeEach(() => {
vi.useFakeTimers()
vi.setSystemTime(new Date('2024-01-15T10:00:00Z')) // deterministic "now"
})
afterEach(() => {
vi.useRealTimers()
})
it('retries after 5 seconds', async () => {
const promise = retryWithDelay(operation, { delayMs: 5000, maxAttempts: 3 })
await vi.advanceTimersByTimeAsync(5000) // advances fake clock AND flushes promises
expect(operation).toHaveBeenCalledTimes(2)
})Poor data setup is the second most common source of flaky or hard-to-read tests.
Object Mother / Factory function pattern:
// src/test/factories/user.factory.ts
import { User } from '../domain/user'
let idCounter = 0
export function createUser(overrides: Partial<User> = {}): User {
return {
id: `user-${++idCounter}`,
email: `user${idCounter}@example.com`,
name: 'Test User',
role: 'member',
createdAt: new Date('2024-01-01T00:00:00Z'),
isActive: true,
...overrides,
}
}
// Usage in tests -- explicit only what matters:
const adminUser = createUser({ role: 'admin' })
const inactiveUser = createUser({ isActive: false, email: 'inactive@example.com' })Reset state between tests:
Reset the idCounter in beforeEach or use a closure that resets on module load per test
In Vitest, use vi.isolateModules() to get a fresh module instance including its internal state
Never share mutable fixtures between describe blocks across different test files
Database fixture seeding:
For integration tests with a real database, use a transaction-per-test strategy: begin a transaction in beforeEach, run the test, rollback in afterEach -- no cleanup queries needed
For read-heavy integration tests, seed once in beforeAll and use read-only fixtures
Use a dedicated test database with a name suffix (_test) -- never the development or staging database
it.each / test.each eliminates copy-paste test duplication while maintaining readable output.
describe('validateEmail', () => {
it.each([
// [input, expected, description]
['user@example.com', true, 'standard email'],
['user+tag@example.com', true, 'plus-addressed email'],
['user@sub.domain.co', true, 'subdomain email'],
['', false, 'empty string'],
['notanemail', false, 'missing @ symbol'],
['@nodomain.com', false, 'missing local part'],
['user@', false, 'missing domain'],
['user @example.com', false, 'space in local part'],
])('returns %s for "%s" (%s)', (input, expected, _description) => {
expect(validateEmail(input)).toBe(expected)
})
})Template literal version for readability:
it.each`
price | qty | expected
${10} | ${3} | ${30}
${25.50} | ${2} | ${51}
${0} | ${5} | ${0}
`('price=$price qty=$qty -> total=$expected', ({ price, qty, expected }) => {
expect(calculateTotal(price, qty)).toBeCloseTo(expected, 2)
})When NOT to use it.each:
When each case requires substantially different setup or teardown logic -- write separate named tests
When the parameterized table obscures the business intent -- a test named "should reject negative prices" is more scannable than a row in a table
Snapshots are useful for large output objects but become a liability when overused.
Inline snapshots (preferred for small outputs):
it('formats a user profile card', () => {
const result = formatProfileCard({ name: 'Alice', role: 'admin', joinYear: 2022 })
expect(result).toMatchInlineSnapshot(`
{
"badge": "Admin",
"displayName": "Alice",
"memberSince": "2022",
"subtitle": "Administrator since 2022",
}
`)
})File snapshots (for large outputs like HTML, SQL, or serialized ASTs):
Snapshots live in __snapshots__/filename.test.ts.snap
Run vitest --update-snapshots or jest --updateSnapshot to regenerate
Always review snapshot diffs in PRs -- a snapshot change is a behavior change
Exclude dynamic values before snapshotting: strip timestamps, random IDs, and environment-specific paths using expect.any(Date) or a custom serializer
Custom snapshot serializer example:
// Strips UUIDs from snapshot output
expect.addSnapshotSerializer({
test: (val) => typeof val === 'string' && /[0-9a-f-]{36}/.test(val),
print: () => '"[UUID]"',
})When to avoid snapshots:
Do not snapshot primitive values (expect(count).toBe(5) is clearer than a snapshot)
Do not snapshot error messages that change frequently
Do not snapshot entire API responses -- assert on specific fields that represent the contract
Coverage gates prevent regression but must be configured carefully to avoid false confidence.
V8 provider (provider: 'v8'): Uses Node.js's built-in V8 coverage engine. Fast, no instrumentation overhead, but branch detection can miss certain patterns (short-circuit evaluation, optional chaining).
Istanbul provider (provider: 'istanbul'): Instruments code at build time. 20-40% slower but more accurate branch coverage, especially for ??, ?., and ternary expressions.
Recommended thresholds for production services: lines ≥ 80%, branches ≥ 75%, functions ≥ 80%. Do not set 100% -- it incentivizes testing implementation details over behavior.
Per-file thresholds (Vitest ≥ 1.0): Use perFile: true in thresholds to catch new files added without tests rather than letting them be absorbed by global averages.
Exclude patterns that must always be excluded: migration files, generated GraphQL types, Prisma client output, configuration files, barrel index files (index.ts that only re-export), and type declaration files.
// vitest.config.ts coverage exclusions
coverage: {
exclude: [
'src/**/*.d.ts',
'src/**/__mocks__/**',
'src/test/**',
'src/**/index.ts', // barrel files
'src/generated/**', // codegen output
'src/migrations/**',
'**/*.config.{ts,js}',
'**/*.stories.{ts,tsx}', // Storybook
],
}When advising on JavaScript testing setup, produce a response structured as follows:
## Testing Configuration Decision
**Runner Selected:** [Vitest | Jest] -- [one-sentence justification]
**TypeScript Strategy:** [native | ts-jest | babel-jest] -- [reason]
**Environment:** [node | jsdom | happy-dom] -- [reason]
**Coverage Provider:** [v8 | istanbul] -- [reason]
---
## Configuration File
[Full vitest.config.ts or jest.config.ts with comments]
---
## Test File Structure
// File: src/[module-path]/[module].test.ts
import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest'
// or: import { describe, it, expect, jest } from '@jest/globals'
// Module mock (hoisted automatically -- declare before imports logically)
vi.mock('[dependency-path]', () => ({
[exportedName]: vi.fn([default-behavior]),
}))
// Factory for test data
function create[Entity](overrides = {}) {
return { [fields with sensible defaults], ...overrides }
}
describe('[ModuleUnderTest]', () => {
let [subject]: [SubjectType]
beforeEach(() => {
vi.clearAllMocks()
[subject] = new [Module]({ [dep]: mock[Dep] })
})
afterEach(() => {
vi.restoreAllMocks()
})
describe('[methodName]', () => {
it('[behavior] when [condition]', async () => {
// Arrange
const input = create[Entity]({ [relevant override] })
mock[Dep].[method].mockResolvedValue([test-response])
// Act
const result = await [subject].[method](input)
// Assert
expect(result).toEqual([expected-value])
expect(mock[Dep].[method]).toHaveBeenCalledOnce()
expect(mock[Dep].[method]).toHaveBeenCalledWith([expected-args])
})
it.each([
[[input1], [expected1], '[case description 1]'],
[[input2], [expected2], '[case description 2]'],
])('[behavior]: %s -> %s (%s)', (input, expected) => {
expect([subject].[method](input)).toEqual(expected)
})
})
})
---
## Coverage Thresholds
| Metric | Threshold | Rationale |
|------------|-----------|----------------------------------------|
| Lines | 80% | Baseline for production services |
| Branches | 75% | Lower -- edge branches often impractical |
| Functions | 80% | Every public function should be called |
| Statements | 80% | Aligned with lines threshold |
---
## Mock Strategy Summary
| Dependency Type | Strategy | Tool |
|-------------------------|-----------------------------------|-----------------------|
| Internal module | vi.mock / jest.mock (static) | vi.mock('../service') |
| Pure ESM npm package | Adapter wrapper + mock wrapper | Wrap then vi.mock |
| Node built-in (fs, http)| vi.spyOn on namespace import | vi.spyOn(fs, 'read') |
| Time / Date | Fake timers + setSystemTime | vi.useFakeTimers() |
| HTTP calls | MSW (mock service worker) | setupServer() |
| Database | Repository interface mock | vi.fn() per method |Never mock what you do not own without a wrapper. If you mock axios, node-fetch, or pg directly, your tests break every time the library changes its API. Wrap external I/O in a thin adapter (HttpClient, DatabaseClient) and mock only the adapter. This keeps mocks stable and the production boundary explicit.
ESM module mocks must be declared before the import that uses them. Both vi.mock() and jest.mock() are hoisted by the test runner's transform, but the factory function must not reference variables declared in the test file scope using let or const -- only vi.fn() calls and literals. Breaking this rule causes "Cannot access before initialization" errors that appear non-deterministically.
vi.clearAllMocks() vs vi.resetAllMocks() vs vi.restoreAllMocks() are not interchangeable. clearAllMocks clears call history and instances but keeps implementations. resetAllMocks also removes mock implementations (returns undefined by default). restoreAllMocks restores spyOn mocks to their original implementations. Call clearAllMocks in beforeEach for normal cleanup; call restoreAllMocks in afterEach when using spyOn on real modules.
Never use expect.assertions(n) as your only async guard. Always await the async result directly. expect.assertions(1) catches missed assertions but does not prevent a test from passing if the assertion fires in an unrelated path. Combine await with explicit assertion counts only for rejection-path tests.
Set testTimeout explicitly for integration tests. Vitest's default timeout is 5000ms; Jest's is 5000ms. Network-dependent or database-backed integration tests need 15000--30000ms. Set the timeout at the describe level using vi.setConfig({ testTimeout: 20000 }) or the timeout option in it('...', fn, timeout) -- do not raise the global timeout for the whole suite.
Do not import from vitest and use Jest globals simultaneously. When globals: true is set in Vitest config, describe/it/expect are injected globally. Explicitly importing them from vitest still works but creates confusion. Pick one pattern and enforce it with an ESLint rule (eslint-plugin-vitest rule no-import-node-test or consistent-test-it).
Snapshot files must be committed to version control. Treating __snapshots__ directories as build artifacts causes CI to fail on the first run in a clean environment. Add a lint rule or CI step that fails if snapshot files are listed in .gitignore.
Coverage thresholds should increase monotonically over the life of a project. Never lower a coverage threshold to make CI pass. If a feature is added without tests, the correct response is to write the tests, not to drop the threshold. Track threshold history in the config file's git log as documentation.
Parallel test execution requires shared resource isolation. Tests that write to the filesystem, a database, or a shared port must either use unique resource identifiers per test (e.g., a UUID-named temp directory, a randomly assigned port) or run serially with --pool forks --poolOptions.forks.singleFork true. Never assume test files run in a predictable order.
Type-level tests belong in the test suite. Use expectTypeOf (Vitest) or tsd (Jest-compatible) to assert that TypeScript types are correct. For a function parseDate(s: string): Date, assert expectTypeOf(parseDate).returns.toEqualTypeOf<Date>(). These catch type regressions that no runtime assertion can catch and document the public API contract in executable form.
Packages like nanoid v4, chalk v5, execa v7, node-fetch v3, and p-queue v7 ship only ESM. In Jest + CommonJS environments, jest.mock() fails because Jest's module registry cannot intercept ESM static imports without full ESM experimental mode.
Handling approach:
For each pure-ESM package your code depends on, create a thin adapter: src/lib/idGenerator.ts wraps nanoid, exports generateId. Mock ../lib/idGenerator instead of nanoid.
Alternatively, configure transformIgnorePatterns in Jest to compile the specific ESM package: transformIgnorePatterns: ['node_modules/(?!(nanoid|chalk)/)']. Add @babel/plugin-transform-modules-commonjs to the Babel config used by Jest.
In Vitest, no workaround is needed -- vi.mock('nanoid') works as expected because Vitest operates on the native ESM graph.
Projects using "paths" in tsconfig.json (e.g., @/* mapping to src/*) frequently fail because the test runner does not read tsconfig.json paths automatically.
Handling approach:
In Vitest: Add vite-plugin-tsconfig-paths to vitest.config.ts plugins. This reads tsconfig.json and configures Vite's resolver automatically.
In Jest: Add moduleNameMapper entries in jest.config.ts that mirror each paths entry: '^@/(.*)$': '<rootDir>/src/$1'. Use jest-resolve-tsconfig-paths to automate this mapping from tsconfig.json.
Validate the resolution by running a single test that imports a path-aliased module: vitest run src/test/alias-resolution.test.ts.
Date and Math.random() for Deterministic TestsTests involving timestamp generation, UUID creation, or randomized behavior are non-deterministic by default, causing flaky assertions.
Handling approach:
Use vi.setSystemTime(new Date('2024-06-01T12:00:00Z')) inside beforeEach after calling vi.useFakeTimers(). new Date() and Date.now() return deterministic values.
Mock Math.random with vi.spyOn(Math, 'random').mockReturnValue(0.5) for tests that depend on random behavior.
For UUID generation: mock the crypto.randomUUID method directly: vi.spyOn(crypto, 'randomUUID').mockReturnValue('00000000-0000-0000-0000-000000000001').
Always restore real timers and random in afterEach -- leaked fake timers are the most common source of "passes locally, fails in CI" bugs.
This is caused by shared mutable state: module-level variables, uncleaned DOM state, or singleton instances that persist across tests.
Diagnosis: Run vitest --reporter verbose and look for tests that pass when run with vitest run src/specific.test.ts but fail in the full suite. The failing test runs after a test that corrupts shared state.
Handling approach:
Add vi.isolateModules() wrapping the import of modules that maintain module-level state (e.g., a singleton registry or a connection pool stored in module scope).
For DOM tests, call document.body.innerHTML = '' in afterEach or use @testing-library/react's cleanup() which is called automatically when imported.
Enable --sequence.shuffle in CI: vitest run --sequence.shuffle --sequence.seed 42. If tests fail with shuffle that pass without it, there is state pollution. The seed makes the failure reproducible.
Set isolate: true in Vitest config to give each test file its own module registry (this is the default) -- do not disable it for convenience.
Dynamic import() calls and code paths that only execute in specific environments (e.g., if (process.env.NODE_ENV === 'production')) frequently appear as uncovered branches.
Handling approach:
For dynamic imports, write a test that exercises the code path and awaits the import: const module = await import('../heavyFeature'); module.run().
For environment-conditional code, use vi.stubEnv('NODE_ENV', 'production') (Vitest ≥ 0.28) or process.env.NODE_ENV = 'production' with a restore in afterEach. Never hardcode process.env changes without restoring them.
For code that is genuinely not testable (platform-specific native bindings, catastrophic error paths), use Istanbul/V8 ignore comments sparingly: /* v8 ignore next 3 */ or /* istanbul ignore next */. Document why the ignore is justified in the same comment.
Unit test suites taking over 3 minutes indicate incorrect configuration, not a fundamental performance limit.
Diagnosis checklist:
--coverage enabled during unit test runs adds 30-60% overhead. Run coverage only on scheduled CI runs or pre-merge checks, not on every push.
environment: 'jsdom' initialized for every test file adds ~100ms per file. Use environment: 'node' as the default and scope JSDOM to specific globs: environmentMatchGlobs: [['src/components/**', 'jsdom']].
Watch for globalSetup that starts real servers or databases synchronously -- these serialize all test file startup. Use in-memory alternatives (SQLite, msw mock server) for unit/integration tests.
Vitest's pool: 'threads' with maxWorkers defaulting to os.cpus().length - 1 is optimal for CPU-bound tests. For I/O-bound tests (hitting a real database), limit workers to prevent connection pool exhaustion: poolOptions: { threads: { maxWorkers: 4 } }.
Run vitest bench or measure with --reporter verbose to identify the 10 slowest test files. Those files contain the optimization opportunities.
AbortController, Streams, or Web APIsNode.js 18+ includes fetch, ReadableStream, AbortController, and Blob globally, but older Node.js versions and some Jest environments do not. Tests referencing these globals fail with "ReferenceError: fetch is not defined".
Handling approach:
For Node.js 16-17: polyfill in setupFiles: import 'whatwg-fetch' or import { fetch } from 'undici' and assign to globalThis.fetch.
For AbortController tests: exercise the signal's abort() method directly in tests -- do not rely on timeout behavior. const controller = new AbortController(); controller.abort(); expect(controller.signal.aborted).toBe(true).
For streams: use Node.js stream.Readable.from([...data]) to create test streams without file I/O.
MSW (Mock Service Worker) v2 with the node integration handles fetch interception correctly in Node.js 18+ test environments without polyfills.
Input from user: "I'm starting a new TypeScript project with Vite and Node.js 20. I need to test a UserService class that has a dependency on a UserRepository (database) and sends welcome emails via an email service. What testing setup should I use and how do I write the tests?"
Output:
Runner Selected: Vitest -- The project uses Vite, so Vitest shares the same config and plugin pipeline with zero duplication. Native TypeScript and ESM support eliminate the need for Babel or ts-jest transforms.
TypeScript Strategy: Native (Vitest handles .ts files directly via esbuild transform built into Vite)
Environment: node -- This is a server-side service with no browser globals needed.
Coverage Provider: istanbul -- More accurate branch coverage for TypeScript conditional logic and optional chaining patterns common in service layers.
// vitest.config.ts
import { defineConfig } from 'vitest/config'
import tsconfigPaths from 'vite-plugin-tsconfig-paths'
export default defineConfig({
plugins: [tsconfigPaths()],
test: {
globals: true,
environment: 'node',
include: ['src/**/*.test.ts'],
exclude: ['node_modules', 'dist'],
setupFiles: ['./src/test/setup.ts'],
coverage: {
provider: 'istanbul',
reporter: ['text', 'lcov', 'html'],
include: ['src/**/*.ts'],
exclude: [
'src/**/*.d.ts',
'src/**/*.test.ts',
'src/test/**',
'src/**/index.ts',
'src/generated/**',
],
thresholds: {
lines: 80,
branches: 75,
functions: 80,
statements: 80,
},
},
},
})// src/test/setup.ts
import { vi, afterEach } from 'vitest'
afterEach(() => {
vi.restoreAllMocks()
vi.useRealTimers()
})// src/domain/user.ts
export interface User {
id: string
email: string
name: string
role: 'member' | 'admin'
createdAt: Date
isActive: boolean
}
// src/repositories/userRepository.ts
export interface UserRepository {
findById(id: string): Promise<User | null>
findByEmail(email: string): Promise<User | null>
save(user: Omit<User, 'id' | 'createdAt'>): Promise<User>
}
// src/services/emailService.ts
export interface EmailService {
sendWelcomeEmail(to: string, name: string): Promise<{ messageId: string }>
}// src/services/userService.test.ts
import { describe, it, expect, beforeEach, vi } from 'vitest'
import { UserService } from './userService'
import type { UserRepository } from '../repositories/userRepository'
import type { EmailService } from './emailService'
import type { User } from '../domain/user'
// ── Test Data Factory ──────────────────────────────────────────────────────
let userIdCounter = 0
function createUser(overrides: Partial<User> = {}): User {
const id = `user-${++userIdCounter}`
return {
id,
email: `${id}@example.com`,
name: 'Test User',
role: 'member',
createdAt: new Date('2024-01-15T10:00:00Z'),
isActive: true,
...overrides,
}
}
// ── Mocks ─────────────────────────────────────────────────────────────────
function createMockUserRepository(): UserRepository {
return {
findById: vi.fn(),
findByEmail: vi.fn(),
save: vi.fn(),
}
}
function createMockEmailService(): EmailService {
return {
sendWelcomeEmail: vi.fn(),
}
}
// ── Tests ─────────────────────────────────────────────────────────────────
describe('UserService', () => {
let userRepository: UserRepository
let emailService: EmailService
let userService: UserService
beforeEach(() => {
userIdCounter = 0 // reset counter for deterministic IDs
userRepository = createMockUserRepository()
emailService = createMockEmailService()
userService = new UserService({ userRepository, emailService })
// Deterministic timestamps for all tests in this suite
vi.useFakeTimers()
vi.setSystemTime(new Date('2024-01-15T10:00:00Z'))
})
// ── registerUser ─────────────────────────────────────────────────────────
describe('registerUser', () => {
it('creates a new user and sends a welcome email when the email is not taken', async () => {
// Arrange
const input = { email: 'alice@example.com', name: 'Alice', role: 'member' as const }
const savedUser = createUser({ email: input.email, name: input.name })
vi.mocked(userRepository.findByEmail).mockResolvedValue(null)
vi.mocked(userRepository.save).mockResolvedValue(savedUser)
vi.mocked(emailService.sendWelcomeEmail).mockResolvedValue({ messageId: 'msg-001' })
// Act
const result = await userService.registerUser(input)
// Assert -- returned value
expect(result).toEqual(savedUser)
// Assert -- repository was called with correct args
expect(userRepository.findByEmail).toHaveBeenCalledOnce()
expect(userRepository.findByEmail).toHaveBeenCalledWith('alice@example.com')
expect(userRepository.save).toHaveBeenCalledOnce()
expect(userRepository.save).toHaveBeenCalledWith({
email: 'alice@example.com',
name: 'Alice',
role: 'member',
isActive: true,
})
// Assert -- email was sent after successful save
expect(emailService.sendWelcomeEmail).toHaveBeenCalledOnce()
expect(emailService.sendWelcomeEmail).toHaveBeenCalledWith('alice@example.com', 'Alice')
})
it('throws ConflictError when the email is already registered', async () => {
// Arrange
const existingUser = createUser({ email: 'taken@example.com' })
vi.mocked(userRepository.findByEmail).mockResolvedValue(existingUser)
// Act & Assert
await expect(
userService.registerUser({ email: 'taken@example.com', name: 'Bob', role: 'member' })
).rejects.toThrow('Email already registered: taken@example.com')
// Assert -- no save or email when conflict detected
expect(userRepository.save).not.toHaveBeenCalled()
expect(emailService.sendWelcomeEmail).not.toHaveBeenCalled()
})
it('does not send welcome email when repository save fails', async () => {
// Arrange
vi.mocked(userRepository.findByEmail).mockResolvedValue(null)
vi.mocked(userRepository.save).mockRejectedValue(new Error('Database connection lost'))
// Act & Assert
await expect(
userService.registerUser({ email: 'new@example.com', name: 'Carol', role: 'member' })
).rejects.toThrow('Database connection lost')
expect(emailService.sendWelcomeEmail).not.toHaveBeenCalled()
})
})
// ── getUserById ──────────────────────────────────────────────────────────
describe('getUserById', () => {
it('returns the user when found', async () => {
const user = createUser({ id: 'user-99' })
vi.mocked(userRepository.findById).mockResolvedValue(user)
const result = await userService.getUserById('user-99')
expect(result).toEqual(user)
expect(userRepository.findById).toHaveBeenCalledWith('user-99')
})
it('throws NotFoundError when user does not exist', async () => {
vi.mocked(userRepository.findById).mockResolvedValue(null)
await expect(userService.getUserById('missing-id')).rejects.toThrow(
'User not found: missing-id'
)
})
})
// ── Role validation -- parameterized ─────────────────────────────────────
describe('registerUser role validation', () => {
it.each([
['member', true, 'standard member role is valid'],
['admin', true, 'admin role is valid'],
['guest', false, 'guest is not a permitted role'],
['', false, 'empty string is not a permitted role'],
['ADMIN', false, 'roles are case-sensitive'],
] as const)('role="%s" isValid=%s (%s)', async (role, isValid, _description) => {
vi.mocked(userRepository.findByEmail).mockResolvedValue(null)
const action = () =>
userService.registerUser({ email: 'x@example.com', name: 'X', role: role as any })
if (isValid) {
vi.mocked(userRepository.save).mockResolvedValue(createUser({ role: role as any }))
vi.mocked(emailService.sendWelcomeEmail).mockResolvedValue({ messageId: 'ok' })
await expect(action()).resolves.toBeDefined()
} else {
await expect(action()).rejects.toThrow('Invalid role')
}
})
})
})| Metric | Threshold | Rationale |
|---|---|---|
| Lines | 80% | Baseline for production services |
| Branches | 75% | Lower -- some error branches require complex setup |
| Functions | 80% | Every public method on UserService must be called |
| Statements | 80% | Aligned with lines threshold |
| Dependency | Strategy | Tool |
|---|---|---|
| UserRepository | Interface-based mock factory | vi.fn() per method |
| EmailService | Interface-based mock factory | vi.fn() per method |
Date.now() / new Date() | Fake timers + setSystemTime | vi.useFakeTimers() |
| Database (future) | Transaction rollback per test | Real DB in beforeEach |
| HTTP email API | MSW setupServer with node integration | @mswjs/msw v2 |
Running the tests:
# Run once
npx vitest run
# Watch mode (re-runs affected tests on file save)
npx vitest
# Coverage report
npx vitest run --coverage
# Update snapshots
npx vitest run --update-snapshots
# Type check alongside tests (Vitest ≥ 0.30)
npx vitest --typecheckSKILL.md
863 lines · 4,973 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
JavaScript Testing Patterns bot
Waiting in your sidebar once you say go.
jest.useFakeTimers() becomes vi.useFakeTimers() -- behavior is nearly identicalGlobals (describe, it, expect) are opt-in in Vitest via globals: true in config -- set this first to avoid modifying every test file during migration
No account needed · Runs on the AI plan you already pay for