Spying on Default Exports in Vitest

Spying on a named export is easy; spying on a default export is where teams stall. vi.spyOn(module, 'default') sometimes works, sometimes throws Cannot redefine property, and sometimes silently spies on a copy that the real code never calls. This guide is for engineers on Vitest 1.x or 2.x who need to observe or replace a module’s default export — a default-exported logger, a singleton client, a React component, or a factory function — without breaking the callers that import it. The reliable approach depends on whether the default is an object or a function and on the ESM live-binding rules that make imported names read-only. It is a focused technique within module and dependency mocking, and mastering it closes the last common gap in module isolation.

Root Cause Analysis

The difficulty has two sources. The first is that an ES module’s imported binding is read-only and live: when you write import logger from './logger', logger is a reference into the module, and you cannot reassign it from the outside. So the naive instinct — logger.default = vi.fn() or reassigning the import — is impossible for a function default, because there is no writable property to swap. vi.spyOn needs a host object with a configurable property to wrap, and a bare function default does not present one to the importer.

The second source is what the default actually is. If the default export is an object (export default { info, error }), then the object is a mutable host and vi.spyOn(loggerModule.default, 'info') works cleanly — you are spying on a method of an object, not on the binding itself. But if the default is a function (export default function send() {}), there is no method to spy on; you must replace the whole default binding through vi.mock, because that is the only mechanism that can substitute a module binding rather than a property. Confusing these two cases is why the same vi.spyOn line works in one file and throws in another.

Interop compounds it. As covered in mocking ES modules vs CommonJS in Vitest, a CommonJS default arrives through an interop layer, so the property you try to spy on may sit one level deeper than you expect. The fix is always to match your spy target to how the consumer dereferences the default, and to prefer vi.mock with a factory whenever the default is a function you need to fully control.

Reproducible Setup

Create two modules, one with an object default and one with a function default, so both cases are in play.

npm install -D vitest

// src/logger.ts  (object default)
export default {
  info: (msg: string) => console.log(`[info] ${msg}`),
  error: (msg: string) => console.error(`[error] ${msg}`),
};

// src/send.ts  (function default)
export default function send(to: string): Promise<{ ok: boolean }> {
  return fetch('/api/send', { method: 'POST', body: to }).then(() => ({ ok: true }));
}

// src/service.ts
import logger from './logger';
import send from './send';

export async function dispatch(to: string) {
  logger.info(`dispatching to ${to}`);
  return send(to);
}

Implementation

Step 1 — Spy on a method of an object default. When the default is an object, import it and spy on the method directly. Because the object is a shared mutable reference, the spy applies to the same instance the service uses. Restore afterward so the wrapper does not leak.

// src/service.logger.test.ts
import { vi, it, expect, afterEach } from 'vitest';
import logger from './logger';
import { dispatch } from './service';

afterEach(() => vi.restoreAllMocks());

it('logs before dispatching', async () => {
  const infoSpy = vi.spyOn(logger, 'info').mockImplementation(() => {});
  await dispatch('ada@example.com');
  expect(infoSpy).toHaveBeenCalledWith('dispatching to ada@example.com');
});

Step 2 — Replace a function default with a vi.mock factory. A function default has no property to spy on, so mock the module and expose a spy under default. The imported send then is the spy.

import { vi, it, expect } from 'vitest';
import send from './send';
import { dispatch } from './service';

vi.mock('./send', () => ({ default: vi.fn().mockResolvedValue({ ok: true }) }));

it('calls the default send exactly once', async () => {
  await dispatch('grace@example.com');
  expect(vi.mocked(send)).toHaveBeenCalledWith('grace@example.com');
});

Step 3 — Preserve the real default while spying, when needed. If you want the genuine function to still run but observe its calls, combine vi.importActual with a factory that wraps the original in vi.fn. This keeps behaviour real and records interactions — a partial approach detailed in partial mocking with vi.importactual.

vi.mock('./send', async (importOriginal) => {
  const actual = await importOriginal<typeof import('./send')>();
  return { default: vi.fn(actual.default) };
});

Step 4 — Type the spy target. Use vi.mocked(send) for function defaults and vi.spyOn for object methods; both preserve signatures so a changed argument shape fails at compile time rather than at runtime. Never cast through any to force a spy — a cast hides exactly the drift the test should catch.

Verification

Confirm the spy is wired to the same reference the code under test calls, not a copy. For an object default, assert the method reports as a mock and that it recorded the call. For a function default, assert through vi.mocked and check the call count so a stray extra invocation is caught.

import { vi, it, expect } from 'vitest';
import logger from './logger';
import send from './send';
import { dispatch } from './service';

vi.mock('./send', () => ({ default: vi.fn().mockResolvedValue({ ok: true }) }));

it('observes both defaults on the real path', async () => {
  const infoSpy = vi.spyOn(logger, 'info').mockImplementation(() => {});
  await dispatch('lin@example.com');
  expect(infoSpy).toHaveBeenCalledTimes(1);
  expect(vi.isMockFunction(send)).toBe(true);
  expect(send).toHaveBeenCalledTimes(1);
});

If the object-default spy reports zero calls while the code clearly logs, you likely spied on a re-imported object that differs from the service’s reference — ensure both import the same module specifier so they share one instance.

The recurring theme across every default-export failure is reference identity: a spy only works when it wraps the exact value the code under test reaches for. For an object default that means one shared object instance; for a function default it means the module binding itself, which is why replacement rather than property-spying is the only reliable route. When a spy mysteriously records nothing, resist adding retries or timing hacks and instead confirm the two sides resolve to the same module record — mismatched path aliases and duplicated package copies in a monorepo are the usual culprits.

Troubleshooting

Cannot redefine property: default. Diagnosis: you tried vi.spyOn(module, 'default') on a namespace whose default is non-configurable, which is common for transformed ESM. Fix: for a function default, do not spy on the binding — replace it with a vi.mock factory that returns { default: vi.fn() }. Reserve vi.spyOn for methods of an object default.

The spy never fires even though the code runs. Diagnosis: the test and the module under test imported two different instances of the default — often because one used a path alias and the other a relative path. Fix: normalize import specifiers so they resolve to one module, and remember that ESM live bindings mean the service reads the binding by reference, so both sides must point at the same module record.

Default is undefined inside the mock. Diagnosis: the module is CommonJS and the default arrives through interop one level down. Fix: shape the factory to match, exposing the value under default and, if consumers also read it directly, at the top level too — the dual-shape pattern from mocking ES modules vs CommonJS in Vitest.

FAQ

Related

• Back to Module & Dependency Mocking
• Mocking ES modules vs CommonJS in Vitest — resolve default-export interop across module formats.
• Partial mocking with vi.importActual — keep the real default running while spying on it.
• Avoiding vi.mock hoisting pitfalls — apply hoist-safe factories when replacing a function default.
• Vitest configuration & setup — set restoreMocks and clearMocks so spies never leak.