> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# Mocks

> Mock functions and modules with Bun's built-in mocking utilities

Bun provides a Jest-compatible mocking API. You can mock functions, spy on objects, and mock entire modules.

## Mock functions

Create a mock function with `mock()`:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("mock function", () => {
  const mockFn = mock(() => "mocked");
  
  const result = mockFn();
  
  expect(result).toBe("mocked");
  expect(mockFn).toHaveBeenCalled();
  expect(mockFn).toHaveBeenCalledTimes(1);
});
```

### Mock implementation

Control the return value of a mock:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("mock implementation", () => {
  const mockFn = mock((a: number, b: number) => a + b);
  
  expect(mockFn(2, 3)).toBe(5);
  expect(mockFn).toHaveBeenCalledWith(2, 3);
});
```

### Mock return values

Set return values without providing a full implementation:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("mock return value", () => {
  const mockFn = mock();
  mockFn.mockReturnValue(42);
  
  expect(mockFn()).toBe(42);
  expect(mockFn()).toBe(42);
});

test("mock return value once", () => {
  const mockFn = mock();
  mockFn.mockReturnValueOnce(1).mockReturnValueOnce(2).mockReturnValue(3);
  
  expect(mockFn()).toBe(1);
  expect(mockFn()).toBe(2);
  expect(mockFn()).toBe(3);
  expect(mockFn()).toBe(3);
});
```

### Mock resolved/rejected values

For async functions:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("mock resolved value", async () => {
  const mockFn = mock();
  mockFn.mockResolvedValue("success");
  
  const result = await mockFn();
  expect(result).toBe("success");
});

test("mock rejected value", async () => {
  const mockFn = mock();
  mockFn.mockRejectedValue(new Error("failed"));
  
  await expect(mockFn()).rejects.toThrow("failed");
});
```

### Mock implementation once

Provide different implementations for sequential calls:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("mock implementation once", () => {
  const mockFn = mock();
  mockFn
    .mockImplementationOnce(() => "first")
    .mockImplementationOnce(() => "second")
    .mockImplementation(() => "default");
  
  expect(mockFn()).toBe("first");
  expect(mockFn()).toBe("second");
  expect(mockFn()).toBe("default");
  expect(mockFn()).toBe("default");
});
```

## Spying on objects

Use `spyOn()` to spy on methods of an object:

```ts theme={null}
import { test, expect, spyOn } from "bun:test";

test("spy on method", () => {
  const obj = {
    method: () => "original"
  };
  
  const spy = spyOn(obj, "method");
  
  obj.method();
  
  expect(spy).toHaveBeenCalled();
  expect(obj.method()).toBe("original"); // Original implementation preserved
});
```

### Mock implementation

Override the implementation:

```ts theme={null}
import { test, expect, spyOn } from "bun:test";

test("spy with mock implementation", () => {
  const obj = {
    getValue: () => "original"
  };
  
  const spy = spyOn(obj, "getValue").mockImplementation(() => "mocked");
  
  expect(obj.getValue()).toBe("mocked");
  expect(spy).toHaveBeenCalled();
});
```

### Restore original implementation

Restore the original implementation:

```ts theme={null}
import { test, expect, spyOn } from "bun:test";

test("restore spy", () => {
  const obj = {
    method: () => "original"
  };
  
  const spy = spyOn(obj, "method").mockReturnValue("mocked");
  
  expect(obj.method()).toBe("mocked");
  
  spy.mockRestore();
  
  expect(obj.method()).toBe("original");
});
```

### Automatic cleanup with using

Bun supports automatic cleanup with the `using` keyword:

```ts theme={null}
import { test, expect, spyOn } from "bun:test";

test("auto-restore with using", () => {
  const obj = {
    method: () => "original"
  };
  
  {
    using spy = spyOn(obj, "method").mockReturnValue("mocked");
    expect(obj.method()).toBe("mocked");
  } // spy.mockRestore() called automatically
  
  expect(obj.method()).toBe("original");
});
```

## Mock matchers

Check how mock functions were called:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("mock matchers", () => {
  const mockFn = mock();
  
  mockFn("hello", 42);
  mockFn("world", 100);
  
  // Called at all
  expect(mockFn).toHaveBeenCalled();
  
  // Called specific number of times
  expect(mockFn).toHaveBeenCalledTimes(2);
  
  // Called with specific arguments
  expect(mockFn).toHaveBeenCalledWith("hello", 42);
  expect(mockFn).toHaveBeenLastCalledWith("world", 100);
  expect(mockFn).toHaveBeenNthCalledWith(1, "hello", 42);
  expect(mockFn).toHaveBeenNthCalledWith(2, "world", 100);
});
```

## Mock properties

Access mock call history:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("mock properties", () => {
  const mockFn = mock((x: number) => x * 2);
  
  mockFn(5);
  mockFn(10);
  
  // Access call history
  expect(mockFn.mock.calls).toEqual([[5], [10]]);
  expect(mockFn.mock.results).toEqual([
    { type: "return", value: 10 },
    { type: "return", value: 20 }
  ]);
  
  // Call count
  expect(mockFn.mock.calls.length).toBe(2);
});
```

## Clearing and resetting mocks

### mockClear()

Clears call history but preserves mock implementation:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("clear mock", () => {
  const mockFn = mock(() => "mocked");
  
  mockFn();
  expect(mockFn).toHaveBeenCalledTimes(1);
  
  mockFn.mockClear();
  
  expect(mockFn).toHaveBeenCalledTimes(0);
  expect(mockFn()).toBe("mocked"); // Implementation preserved
});
```

### mockReset()

Clears call history and removes mock implementation:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("reset mock", () => {
  const mockFn = mock(() => "mocked");
  
  mockFn();
  mockFn.mockReset();
  
  expect(mockFn).toHaveBeenCalledTimes(0);
  expect(mockFn()).toBeUndefined(); // Returns undefined
});
```

### mockRestore()

Restores original implementation (for spies):

```ts theme={null}
import { test, expect, spyOn } from "bun:test";

test("restore mock", () => {
  const obj = { method: () => "original" };
  const spy = spyOn(obj, "method").mockReturnValue("mocked");
  
  expect(obj.method()).toBe("mocked");
  
  spy.mockRestore();
  
  expect(obj.method()).toBe("original");
});
```

## Module mocking

Mock entire modules with `mock.module()`:

```ts theme={null}
import { test, expect, mock } from "bun:test";

mock.module("./math.ts", () => ({
  add: mock((a: number, b: number) => 100), // Always returns 100
  subtract: mock((a: number, b: number) => 0)
}));

test("mocked module", async () => {
  const { add, subtract } = await import("./math.ts");
  
  expect(add(2, 3)).toBe(100);
  expect(subtract(5, 3)).toBe(0);
  
  expect(add).toHaveBeenCalledWith(2, 3);
});
```

### Partial module mocking

Mock specific exports while keeping others:

```ts theme={null}
import { mock } from "bun:test";

mock.module("./utils.ts", () => {
  const actual = require("./utils.ts");
  return {
    ...actual,
    dangerousFunction: mock(() => "safe")
  };
});
```

## Global mock utilities

### jest.clearAllMocks()

Clears all mocks:

```ts theme={null}
import { test, expect, mock } from "bun:test";

test("clear all mocks", () => {
  const mock1 = mock();
  const mock2 = mock();
  
  mock1();
  mock2();
  
  jest.clearAllMocks();
  
  expect(mock1).toHaveBeenCalledTimes(0);
  expect(mock2).toHaveBeenCalledTimes(0);
});
```

### jest.restoreAllMocks()

Restores all spies:

```ts theme={null}
import { test, expect, spyOn } from "bun:test";

test("restore all mocks", () => {
  const obj1 = { method: () => "original1" };
  const obj2 = { method: () => "original2" };
  
  spyOn(obj1, "method").mockReturnValue("mocked1");
  spyOn(obj2, "method").mockReturnValue("mocked2");
  
  jest.restoreAllMocks();
  
  expect(obj1.method()).toBe("original1");
  expect(obj2.method()).toBe("original2");
});
```

## Related

* [Writing Tests](/test/writing)
* [Lifecycle Hooks](/test/lifecycle)
* [Time Mocking](/test/time)