Skip to content

ever-co/ever-works / .agents/skills/vitest

vitest

Verified

Vitest fast unit testing framework powered by Vite with Jest-compatible API. Use when writing tests, mocking, configuring coverage, or working with test filtering and fixtures.

references/features-mocking.md

View on GitHub
---
name: mocking
description: Mock functions, modules, timers, and dates with vi utilities
---

# Mocking

## Mock Functions

```ts
import { expect, vi } from 'vitest';

// Create mock function
const fn = vi.fn();
fn('hello');

expect(fn).toHaveBeenCalled();
expect(fn).toHaveBeenCalledWith('hello');

// With implementation
const add = vi.fn((a, b) => a + b);
expect(add(1, 2)).toBe(3);

// Mock return values
fn.mockReturnValue(42);
fn.mockReturnValueOnce(1).mockReturnValueOnce(2);
fn.mockResolvedValue({ data: true });
fn.mockRejectedValue(new Error('fail'));

// Mock implementation
fn.mockImplementation((x) => x * 2);
fn.mockImplementationOnce(() => 'first call');
```

## Spying on Objects

```ts
const cart = {
	getTotal: () => 100
};

const spy = vi.spyOn(cart, 'getTotal');
cart.getTotal();

expect(spy).toHaveBeenCalled();

// Mock implementation
spy.mockReturnValue(200);
expect(cart.getTotal()).toBe(200);

// Restore original
spy.mockRestore();
```

## Module Mocking

```ts
// vi.mock is hoisted to top of file
vi.mock('./api', () => ({
	fetchUser: vi.fn(() => ({ id: 1, name: 'Mock' }))
}));

import { fetchUser } from './api';

test('mocked module', () => {
	expect(fetchUser()).toEqual({ id: 1, name: 'Mock' });
});
```

### Partial Mock

```ts
vi.mock('./utils', async (importOriginal) => {
	const actual = await importOriginal();
	return {
		...actual,
		specificFunction: vi.fn()
	};
});
```

### Auto-mock with Spy

```ts
// Keep implementation but spy on calls
vi.mock('./calculator', { spy: true });

import { add } from './calculator';

test('spy on module', () => {
	const result = add(1, 2); // Real implementation
	expect(result).toBe(3);
	expect(add).toHaveBeenCalledWith(1, 2);
});
```

### Manual Mocks (**mocks**)

```
src/
  __mocks__/
    axios.ts      # Mocks 'axios'
  api/
    __mocks__/
      client.ts   # Mocks './client'
    client.ts
```

```ts
// Just call vi.mock with no factory
vi.mock('axios');
vi.mock('./api/client');
```

## Dynamic Mocking (vi.doMock)

Not hoisted - use for dynamic imports:

```ts
test('dynamic mock', async () => {
	vi.doMock('./config', () => ({
		apiUrl: 'http://test.local'
	}));

	const { apiUrl } = await import('./config');
	expect(apiUrl).toBe('http://test.local');

	vi.doUnmock('./config');
});
```

## Mock Timers

```ts
import { afterEach, beforeEach, vi } from 'vitest';

beforeEach(() => {
	vi.useFakeTimers();
});

afterEach(() => {
	vi.useRealTimers();
});

test('timers', () => {
	const fn = vi.fn();
	setTimeout(fn, 1000);

	expect(fn).not.toHaveBeenCalled();

	vi.advanceTimersByTime(1000);
	expect(fn).toHaveBeenCalled();
});

// Other timer methods
vi.runAllTimers(); // Run all pending timers
vi.runOnlyPendingTimers(); // Run only currently pending
vi.advanceTimersToNextTimer(); // Advance to next timer
```

### Async Timer Methods

```ts
test('async timers', async () => {
	vi.useFakeTimers();

	let resolved = false;
	setTimeout(
		() =>
			Promise.resolve().then(() => {
				resolved = true;
			}),
		100
	);

	await vi.advanceTimersByTimeAsync(100);
	expect(resolved).toBe(true);
});
```

## Mock Dates

```ts
vi.setSystemTime(new Date('2024-01-01'));
expect(new Date().getFullYear()).toBe(2024);

vi.useRealTimers(); // Restore
```

## Mock Globals

```ts
vi.stubGlobal(
	'fetch',
	vi.fn(() => Promise.resolve({ json: () => ({ data: 'mock' }) }))
);

// Restore
vi.unstubAllGlobals();
```

## Mock Environment Variables

```ts
vi.stubEnv('API_KEY', 'test-key');
expect(import.meta.env.API_KEY).toBe('test-key');

// Restore
vi.unstubAllEnvs();
```

## Clearing Mocks

```ts
const fn = vi.fn();
fn();

fn.mockClear(); // Clear call history
fn.mockReset(); // Clear history + implementation
fn.mockRestore(); // Restore original (for spies)

// Global
vi.clearAllMocks();
vi.resetAllMocks();
vi.restoreAllMocks();
```

## Config Auto-Reset

```ts
// vitest.config.ts
defineConfig({
	test: {
		clearMocks: true, // Clear before each test
		mockReset: true, // Reset before each test
		restoreMocks: true, // Restore after each test
		unstubEnvs: true, // Restore env vars
		unstubGlobals: true // Restore globals
	}
});
```

## Hoisted Variables for Mocks

```ts
const mockFn = vi.hoisted(() => vi.fn());

vi.mock('./module', () => ({
	getData: mockFn
}));

import { getData } from './module';

test('hoisted mock', () => {
	mockFn.mockReturnValue('test');
	expect(getData()).toBe('test');
});
```

## Key Points

- `vi.mock` is hoisted - called before imports
- Use `vi.doMock` for dynamic, non-hoisted mocking
- Always restore mocks to avoid test pollution
- Use `{ spy: true }` to keep implementation but track calls
- `vi.hoisted` lets you reference variables in mock factories

<!--
Source references:
- https://vitest.dev/guide/mocking.html
- https://vitest.dev/api/vi.html
-->
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall