Mocking Pattern | Bootspring Docs

Mock dependencies effectively in tests using Vitest mock functions, module mocking, timers, and MSW for HTTP requests.

Overview#

Mocking isolates code under test by replacing dependencies with controlled implementations. This enables testing units in isolation and simulating various scenarios.

When to use:

Isolating code from external dependencies
Simulating API responses
Testing time-dependent code
Controlling random values

Key features:

Mock functions with return values
Module mocking for imports
Timer mocking for async code
HTTP mocking with MSW

Code Example#

Mock Functions#

// Basic mock function
import { vi, describe, it, expect } from 'vitest'

const mockFn = vi.fn()
mockFn('arg1', 'arg2')

expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2')
expect(mockFn).toHaveBeenCalledTimes(1)

// Mock with return value
const mockGet = vi.fn().mockReturnValue('result')
const mockAsync = vi.fn().mockResolvedValue({ data: 'test' })

expect(mockGet()).toBe('result')
expect(await mockAsync()).toEqual({ data: 'test' })

// Mock implementation
const mockImpl = vi.fn().mockImplementation((x) => x * 2)
expect(mockImpl(5)).toBe(10)

// Mock return value once
const mockOnce = vi.fn()
  .mockReturnValueOnce('first')
  .mockReturnValueOnce('second')
  .mockReturnValue('default')

expect(mockOnce()).toBe('first')
expect(mockOnce()).toBe('second')
expect(mockOnce()).toBe('default')

Module Mocking#

// __tests__/service.test.ts
import { describe, it, expect, vi } from 'vitest'
import { sendEmail } from '@/lib/email'
import { createUser } from '@/services/user'

// Mock entire module
vi.mock('@/lib/email', () => ({
  sendEmail: vi.fn().mockResolvedValue({ success: true })
}))

describe('createUser', () => {
  it('sends welcome email', async () => {
    await createUser({ email: 'test@example.com', name: 'Test' })

    expect(sendEmail).toHaveBeenCalledWith(
      expect.objectContaining({
        to: 'test@example.com',
        template: 'welcome'
      })
    )
  })
})

// Partial Mocking - keep some real exports
vi.mock('@/lib/utils', async () => {
  const actual = await vi.importActual('@/lib/utils')
  return {
    ...actual,
    generateId: vi.fn().mockReturnValue('test-id')
  }
})

Spy on Methods#

import { vi, describe, it, expect, afterEach } from 'vitest'

describe('spying', () => {
  afterEach(() => {
    vi.restoreAllMocks()
  })

  it('spies without replacing', () => {
    const consoleSpy = vi.spyOn(console, 'log')

    myFunction() // calls console.log internally

    expect(consoleSpy).toHaveBeenCalledWith('expected message')
  })

  it('spies and mocks', () => {
    const dateSpy = vi.spyOn(Date, 'now').mockReturnValue(1234567890)

    expect(Date.now()).toBe(1234567890)

    dateSpy.mockRestore()
  })

  it('spies on object methods', () => {
    const user = {
      getName: () => 'John',
      getAge: () => 30
    }

    const spy = vi.spyOn(user, 'getName').mockReturnValue('Jane')

    expect(user.getName()).toBe('Jane')
    expect(spy).toHaveBeenCalled()
  })
})

Mock Timers#

import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest'
import { debounce } from '@/lib/utils'

describe('debounce', () => {
  beforeEach(() => {
    vi.useFakeTimers()
  })

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

  it('debounces function calls', () => {
    const fn = vi.fn()
    const debounced = debounce(fn, 100)

    debounced()
    debounced()
    debounced()

    expect(fn).not.toHaveBeenCalled()

    vi.advanceTimersByTime(100)

    expect(fn).toHaveBeenCalledTimes(1)
  })

  it('uses fake Date', () => {
    const mockDate = new Date('2024-01-15T12:00:00Z')
    vi.setSystemTime(mockDate)

    expect(new Date()).toEqual(mockDate)
  })

  it('runs all timers', () => {
    const fn = vi.fn()
    setTimeout(fn, 1000)
    setTimeout(fn, 2000)

    vi.runAllTimers()

    expect(fn).toHaveBeenCalledTimes(2)
  })
})

Mock Fetch/HTTP with MSW#

// mocks/handlers.ts
import { http, HttpResponse } from 'msw'

export const handlers = [
  http.get('/api/users', () => {
    return HttpResponse.json([
      { id: '1', name: 'Test User' }
    ])
  }),

  http.post('/api/users', async ({ request }) => {
    const body = await request.json()
    return HttpResponse.json({ id: '2', ...body }, { status: 201 })
  }),

  http.get('/api/users/:id', ({ params }) => {
    return HttpResponse.json({ id: params.id, name: 'User ' + params.id })
  })
]

// mocks/server.ts
import { setupServer } from 'msw/node'
import { handlers } from './handlers'

export const server = setupServer(...handlers)

// vitest.setup.ts
import { server } from './mocks/server'

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

// In tests - override for specific test
import { server } from '@/mocks/server'
import { http, HttpResponse } from 'msw'

it('handles error', async () => {
  server.use(
    http.get('/api/users', () => {
      return HttpResponse.json({ error: 'Not found' }, { status: 404 })
    })
  )

  // Test error handling...
})

Mock Prisma#

// __mocks__/prisma.ts
import { PrismaClient } from '@prisma/client'
import { mockDeep, DeepMockProxy } from 'vitest-mock-extended'

export type MockPrisma = DeepMockProxy<PrismaClient>

export const prismaMock = mockDeep<PrismaClient>()

vi.mock('@/lib/db', () => ({
  prisma: prismaMock
}))

// In test file
import { prismaMock } from '../__mocks__/prisma'

describe('user service', () => {
  beforeEach(() => {
    vi.clearAllMocks()
  })

  it('finds user', async () => {
    prismaMock.user.findUnique.mockResolvedValue({
      id: '1',
      email: 'test@example.com',
      name: 'Test'
    })

    const user = await getUserById('1')
    expect(user.email).toBe('test@example.com')
  })

  it('creates user', async () => {
    prismaMock.user.create.mockResolvedValue({
      id: '2',
      email: 'new@example.com',
      name: 'New User'
    })

    const user = await createUser({ email: 'new@example.com', name: 'New User' })
    expect(user.id).toBe('2')
    expect(prismaMock.user.create).toHaveBeenCalledWith({
      data: expect.objectContaining({ email: 'new@example.com' })
    })
  })
})

Mock Next.js Modules#

// vitest.setup.ts
import { vi } from 'vitest'

// Mock next/navigation
vi.mock('next/navigation', () => ({
  useRouter: () => ({
    push: vi.fn(),
    replace: vi.fn(),
    back: vi.fn(),
    prefetch: vi.fn()
  }),
  usePathname: () => '/',
  useSearchParams: () => new URLSearchParams(),
  useParams: () => ({})
}))

// Mock next/headers
vi.mock('next/headers', () => ({
  headers: () => new Map(),
  cookies: () => ({
    get: vi.fn(),
    set: vi.fn(),
    delete: vi.fn()
  })
}))

// Mock next/cache
vi.mock('next/cache', () => ({
  revalidatePath: vi.fn(),
  revalidateTag: vi.fn()
}))

// In specific test - override mock
import { useRouter } from 'next/navigation'

it('navigates on submit', async () => {
  const push = vi.fn()
  vi.mocked(useRouter).mockReturnValue({ push } as any)

  // Test component that calls router.push
  await submitForm()

  expect(push).toHaveBeenCalledWith('/success')
})

Mock Environment Variables#

import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest'

describe('config', () => {
  const originalEnv = process.env

  beforeEach(() => {
    vi.resetModules()
    process.env = { ...originalEnv }
  })

  afterEach(() => {
    process.env = originalEnv
  })

  it('uses production config', async () => {
    process.env.NODE_ENV = 'production'
    process.env.API_URL = 'https://api.prod.com'

    const { config } = await import('@/lib/config')

    expect(config.apiUrl).toBe('https://api.prod.com')
  })

  it('uses development config', async () => {
    process.env.NODE_ENV = 'development'

    const { config } = await import('@/lib/config')

    expect(config.apiUrl).toBe('http://localhost:3000/api')
  })
})

Usage Instructions#

Choose mocking strategy: Decide between mock functions, module mocks, or MSW
Set up mocks before tests: Use vi.mock() at module level or in beforeEach
Clear mocks between tests: Use vi.clearAllMocks() in beforeEach
Restore mocks after: Use vi.restoreAllMocks() or vi.useRealTimers()
Override for specific tests: Use server.use() for MSW or new mock implementations

Best Practices#

Mock at the boundary - Mock external services, not internal logic
Clear mocks between tests - Prevent state leakage
Use MSW for HTTP - More realistic than mocking fetch directly
Spy before mock - Sometimes spying is enough
Keep mocks simple - Don't over-engineer mock implementations
Document mock behavior - Make it clear what mocks return
Test real code when possible - Only mock what you must

Vitest - Test runner setup
Unit Testing - Unit testing patterns
Fixtures - Test data management
Integration Testing - Integration tests