references/mock-type-safety.md

GitHub
titleMaintain Type Safety in Mocks
impactMEDIUM
impactDescriptionCatches mock/implementation mismatches at compile time instead of runtime
tagsmock, typescript, type-safety, vi.mocked, MockedFunction

Maintain Type Safety in Mocks

Mocks without proper typing can drift from real implementations. When the real function signature changes, untyped mocks continue to compile but tests test the wrong thing.

Incorrect (untyped mocks):

import { describe, it, expect, vi } from 'vitest'
import { fetchUser } from './api'

vi.mock('./api')

describe('UserService', () => {
  it('should fetch user', async () => {
    // No type checking - could return anything
    (fetchUser as any).mockResolvedValue({ name: 'Alice' })
    // Missing 'id' field, but TypeScript doesn't catch it

    const user = await fetchUser(1)
    expect(user.name).toBe('Alice')
  })
})

Correct (properly typed mocks):

import { describe, it, expect, vi, type MockedFunction } from 'vitest'
import { fetchUser, type User } from './api'

vi.mock('./api')

// Type-safe mock reference
const mockedFetchUser = fetchUser as MockedFunction<typeof fetchUser>

describe('UserService', () => {
  it('should fetch user', async () => {
    // TypeScript enforces return type matches User
    mockedFetchUser.mockResolvedValue({ id: 1, name: 'Alice', email: 'a@b.com' })

    const user = await mockedFetchUser(1)
    expect(user).toEqual({ id: 1, name: 'Alice', email: 'a@b.com' })
  })
})

Using vi.mocked helper:

import { describe, it, expect, vi } from 'vitest'
import { fetchUser } from './api'

vi.mock('./api')

describe('UserService', () => {
  it('should fetch user', async () => {
    // vi.mocked provides proper typing automatically
    vi.mocked(fetchUser).mockResolvedValue({
      id: 1,
      name: 'Alice',
      email: 'alice@example.com',
    })

    const user = await fetchUser(1)
    expect(user.name).toBe('Alice')
  })
})

Type-safe mock factories:

function createMockUser(overrides?: Partial<User>): User {
  return {
    id: 1,
    name: 'Test User',
    email: 'test@example.com',
    ...overrides,
  }
}

vi.mocked(fetchUser).mockResolvedValue(createMockUser({ name: 'Alice' }))

Benefits:

  • Compile-time errors when mock returns wrong type
  • IDE autocomplete for mock methods
  • Mocks stay in sync with real implementations

Reference: Vitest vi.mocked