Mock System

Relevant source files

• packages/bun-types/test.d.ts
• src/bun.js/bindings/JSMockFunction.cpp
• src/bun.js/bindings/JSMockFunction.h
• src/bun.js/event_loop.zig
• src/bun.js/test/diff_format.zig
• src/bun.js/test/expect.zig
• src/bun.js/test/jest.classes.ts
• src/bun.js/test/jest.zig
• src/cli/test_command.zig
• test/cli/test/bun-test.test.ts
• test/integration/bun-types/fixture/23347.test.ts
• test/integration/bun-types/fixture/test.ts
• test/js/bun/test/__snapshots__/test-test.test.ts.snap
• test/js/bun/test/expect.test.js
• test/js/bun/test/jest-extended.test.js
• test/js/bun/test/jest-hooks.test.ts
• test/js/bun/test/mock-disposable.test.ts
• test/js/bun/test/mock-fn.test.js
• test/js/bun/test/test-fixture-diff-indexed-properties.js
• test/js/bun/test/test-test.test.ts
• test/js/bun/test/test-timers.test.ts
• test/js/bun/test/todo-test-fixture-2.js
• test/js/bun/test/todo-test-fixture.js
• test/js/third_party/socket.io/socket.io-connection-state-recovery.test.ts
• test/regression/issue/18820.test.ts
• test/regression/issue/issue-12276.test.ts

The Mock System provides Jest and Vitest-compatible function mocking and spying capabilities for Bun's test runner. It enables creating mock functions that record calls and allow controlling return values, simulating errors, and temporarily replacing object methods. This system is part of the Testing Framework (#6) and works in conjunction with the Expect API (#6.2) for assertions on mock behavior.

Architecture Overview

The mock system is implemented across three layers: C++ (JavaScriptCore bindings), Zig (FFI bridge), and JavaScript (public API).

Core Components

Diagram: Mock System Architecture

Sources: src/bun.js/bindings/JSMockFunction.cpp1-1000 src/bun.js/bindings/JSMockFunction.h1-100 src/bun.js/test/jest.zig213-261

JSMockFunction Class

JSMockFunction is the C++ class representing a mock function, extending JSC::InternalFunction to behave as a callable JavaScript function.

Key Properties

Property	Type	Purpose
implementation	WriteBarrier<Unknown>	Head of implementation chain, executed next
fallbackImplementation	WriteBarrier<Unknown>	Default non-once implementation
tail	WriteBarrier<Unknown>	Last once implementation in chain
spyOriginal	WriteBarrier<Unknown>	Original function for spy restoration
calls	WriteBarrier<JSArray>	Array of argument arrays for each call
contexts	WriteBarrier<JSArray>	Array of this values for each call
invocationCallOrder	WriteBarrier<JSArray>	Global invocation order numbers
instances	WriteBarrier<JSArray>	Array of constructed instances (for constructors)
returnValues	WriteBarrier<JSArray>	Array of return values from each call
spyTarget	Weak<JSObject>	Weak reference to spied object
spyIdentifier	Identifier	Property name being spied on
spyAttributes	unsigned	Original property attributes
mock	LazyProperty<JSObject>	Lazy-initialized mock metadata object

Sources: src/bun.js/bindings/JSMockFunction.cpp231-294

Mock Metadata Object

The mock lazy property provides access to call tracking data via getters:

Diagram: Mock Metadata Object Structure

Sources: src/bun.js/bindings/JSMockFunction.cpp432-573

Mock Function Creation

jest.fn() / mock()

Mock functions are created through jest.fn() (aliased as mock() and vi.fn()):

Diagram: Mock Function Creation Flow

The C++ implementation:

1. Creates a JSMockFunction with CallbackKind::Call
2. Copies function name and length from provided implementation
3. Sets the implementation or fallback implementation based on arguments
4. Returns the callable mock function object

Sources: src/bun.js/bindings/JSMockFunction.cpp1193-1301 src/bun.js/test/jest.zig217

JSMockImplementation

JSMockImplementation represents different implementation strategies for mock functions. It forms a linked list for "once" implementations.

Implementation Kinds

Diagram: Implementation Kinds

Kind	Stored Value	Behavior
Call	Function to execute	Calls the function with arguments
ReturnValue	Value to return	Returns the value (resolves if promise)
ReturnThis	(unused)	Returns the this context
RejectedValue	Error value	Rejects with the value

Implementation Chain Structure

Diagram: Implementation Chain

The nextValueOrSentinel field serves dual purpose:

• undefined: No next value, not a once implementation
• jsNumber(1): No next value, is a once implementation
• JSMockImplementation: Next value, is a once implementation

Sources: src/bun.js/bindings/JSMockFunction.cpp144-209

Mock Function Invocation

When a mock function is called, the system:

1. Records the invocation in tracking arrays
2. Determines which implementation to execute
3. Executes the implementation
4. Advances to next implementation if "once"
5. Returns or throws the result

Diagram: Mock Function Invocation Flow

Sources: src/bun.js/bindings/JSMockFunction.cpp574-803

Spying on Objects

Spying allows intercepting calls to existing object methods while preserving the original behavior.

spyOn() Process

Diagram: spyOn Flow

Key aspects:

• Original function stored in spyOriginal field
• Mock function set as implementation to call through
• Weak reference to target prevents memory leaks
• Special handling for getters/setters creates paired mocks
• spyAttributes includes SpyAttributeESModuleNamespace flag for ES module namespace spying

Sources: src/bun.js/bindings/JSMockFunction.cpp1303-1553

Mock Restoration

mockRestore() reverses the spy operation:

1. Checks if mock is a spy (has spyTarget)
2. If target still exists, restores original property
3. For ES module namespaces, uses putDirect() to bypass readonly
4. Removes from ActiveSpySet

Sources: src/bun.js/bindings/JSMockFunction.cpp1050-1120

Mock Control Methods

mockImplementation / mockImplementationOnce

Diagram: Implementation Setting Flow

Sources: src/bun.js/bindings/JSMockFunction.cpp900-1000

mockReturnValue / mockResolvedValue / mockRejectedValue

These methods create implementations with specific return behaviors:

Method	Implementation Kind	Behavior
mockReturnValue(val)	ReturnValue	Returns val (resolves if promise)
mockReturnValueOnce(val)	ReturnValue (once)	Returns val once
mockResolvedValue(val)	ReturnValue	Returns Promise.resolve(val)
mockResolvedValueOnce(val)	ReturnValue (once)	Returns Promise.resolve(val) once
mockRejectedValue(err)	RejectedValue	Returns Promise.reject(err)
mockRejectedValueOnce(err)	RejectedValue (once)	Returns Promise.reject(err) once
mockReturnThis()	ReturnThis	Returns the this context

Sources: src/bun.js/bindings/JSMockFunction.cpp1001-1150

mockClear / mockReset

Diagram: Clear vs Reset Behavior

• mockClear(): Clears call history but preserves implementations
• mockReset(): Clears call history and removes all implementations

Sources: src/bun.js/bindings/JSMockFunction.cpp804-875

Global Mock Management

JSMockModule

JSMockModule manages global state for the mock system within a JSGlobalObject:

Property	Type	Purpose
s_nextInvocationId	static uint64_t	Global counter for call ordering
mockFunctionStructure	LazyProperty<Structure>	Cached structure for JSMockFunction
mockResultStructure	LazyProperty<Structure>	Cached structure for mock results
mockImplementationStructure	LazyProperty<Structure>	Cached structure for implementations
mockObjectStructure	LazyProperty<Structure>	Cached structure for mock metadata
activeSpySetStructure	LazyProperty<Structure>	Cached structure for spy tracking
withImplementationCleanupFunction	LazyProperty<JSFunction>	Cleanup function for temporary implementations

Sources: src/bun.js/bindings/JSMockFunction.h18-50 src/bun.js/bindings/JSMockFunction.cpp110

ActiveSpySet

ActiveSpySet is a WeakSet-like structure that tracks active spies:

Diagram: ActiveSpySet Management

The set uses weak references, so spies are automatically removed when their mock functions are garbage collected.

Sources: src/bun.js/bindings/JSMockFunction.cpp116-143 src/bun.js/bindings/JSMockFunction.cpp1555-1599

Global Mock Operations

jest.clearAllMocks():

• Iterates ActiveSpySet
• Calls mockClear() on each spy
• Does not affect non-spy mock functions

jest.restoreAllMocks():

• Iterates ActiveSpySet
• Calls mockRestore() on each spy
• Removes spies from set as they're restored

Sources: src/bun.js/bindings/JSMockFunction.cpp1601-1678 src/bun.js/test/jest.zig219-220

withImplementation

withImplementation(fn, callback) temporarily changes a mock's implementation:

Diagram: withImplementation Flow

The cleanup is scheduled using the withImplementationCleanupFunction which ensures restoration happens even if the callback throws.

Sources: src/bun.js/bindings/JSMockFunction.cpp1151-1191

Type Definitions

The TypeScript definitions provide the public API surface:

Diagram: Mock Type Structure

Sources: packages/bun-types/test.d.ts17-201

Example Usage Patterns

Basic Mock Creation

Once Implementations

Spying

Sources: test/js/bun/test/mock-fn.test.js35-165