test: support auto-mock for jest.mock(module) / jest.requireMock

docs/test/mocks.mdx

@@ -262,6 +262,47 @@ test("mock.module", async () => {
 
 Like the rest of Bun, module mocks support both `import` and `require`.
 
+### Auto-mocking
+
+Calling `jest.mock(specifier)` (or `mock.module(specifier)`) without a factory auto-mocks the module: the real module is loaded and a mocked copy of its exports is generated. Functions become `jest.fn()` stubs that return `undefined`, classes become mock constructors whose static and prototype methods (including inherited ones) are mocked, nested plain objects are mocked recursively, and primitives, arrays and other exotic objects are preserved.
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+import { test, expect, jest } from "bun:test";
+
+jest.mock("./api-client");
+
+test("auto-mocked module", () => {
+  const { fetchUser } = require("./api-client");
+
+  // fetchUser is a mock function with the real one's name and length.
+  expect(fetchUser("user-1")).toBeUndefined();
+  expect(fetchUser).toHaveBeenCalledWith("user-1");
+
+  // Configure it like any other mock.
+  fetchUser.mockReturnValue({ id: "user-1" });
+});
+```
+
+Because the real module is loaded to generate the mock, its top-level side effects run. The `__mocks__` directory convention is not supported.
+
+### jest.requireMock()
+
+`jest.requireMock(specifier)` returns the mocked exports of a module. If the module was mocked with `jest.mock(specifier)`, the registered mock is returned. Otherwise an auto-mock is generated on demand and cached, without changing what `import` or `require` return for that module.
+
+```ts title="test.ts" icon="/icons/typescript.svg"
+import { test, expect, jest } from "bun:test";
+
+test("requireMock", () => {
+  const mocked = jest.requireMock("./api-client") as any;
+  mocked.fetchUser.mockReturnValue({ id: "user-1" });
+  expect(mocked.fetchUser("user-1")).toEqual({ id: "user-1" });
+
+  // The real module is untouched.
+  const real = require("./api-client");
+  expect(real.fetchUser).not.toBe(mocked.fetchUser);
+});
+```
+
 ### Overriding Already Imported Modules
 
 Calling `mock.module()` overrides the module even if it has already been imported.
@@ -516,10 +557,10 @@ Bun resolves the module specifier the same way it resolves an `import`, supporti
 
 ### Import Timing Effects
 
-- **When mocking before first import**: No side effects from the original module occur
+- **When mocking before first import**: With a factory, no side effects from the original module occur. The no-factory form (auto-mocking) loads the real module to generate the mock, so its side effects do run.
 - **When mocking after import**: The original module's side effects have already happened
 
-For this reason, use `--preload` for mocks that need to prevent side effects.
+For this reason, use `--preload` with a factory for mocks that need to prevent side effects.
 
 ### Live Bindings
 
@@ -644,9 +685,9 @@ test("service calls API correctly", async () => {
 
 ## Notes
 
-### Auto-mocking
+### `__mocks__` directory
 
-Bun does not support the `__mocks__` directory or auto-mocking. If this is blocking you from switching to Bun, [file an issue](https://github.com/oven-sh/bun/issues).
+`jest.mock(specifier)` without a factory generates an auto-mock from the real module's exports (see [Auto-mocking](#auto-mocking) above), but the `__mocks__` directory convention is not supported. If this is blocking you from switching to Bun, [file an issue](https://github.com/oven-sh/bun/issues).
 
 ### ESM vs CommonJS
 

packages/bun-types/test.d.ts

@@ -48,6 +48,16 @@ declare module "bun:test" {
      * ```
      */
     module(id: string, factory: () => any): void | Promise<void>;
+    /**
+     * Auto-mock a module. Every function exported from `id` is replaced with a
+     * mock function that returns `undefined`, classes become mock constructors,
+     * and nested objects are recursively auto-mocked. Primitive exports and
+     * other builtin objects (arrays, dates, regexps, etc.) are preserved.
+     *
+     * The real module is loaded synchronously when this is called so we can
+     * introspect its exports — passing a factory bypasses that.
+     */
+    module(id: string): void | Promise<void>;
     /**
      * Restore the previous value of mocks.
      */
@@ -92,6 +102,19 @@ declare module "bun:test" {
     function clearAllMocks(): void;
     function resetAllMocks(): void;
     function fn<T extends (...args: any[]) => any>(func?: T): Mock<T>;
+    /**
+     * Register a module mock. With a factory, calls to `import`/`require`
+     * for `id` return the factory's return value. Without a factory, the
+     * real module is loaded and an auto-mock is synthesised — functions
+     * become `jest.fn()` stubs, classes become mock constructors, and
+     * nested objects are recursively auto-mocked.
+     */
+    function mock(id: string, factory?: () => any): void | Promise<void>;
+    /**
+     * Return the mocked exports of a module. If `jest.mock(id)` hasn't been
+     * called yet, the module is loaded and auto-mocked on demand.
+     */
+    function requireMock<T = unknown>(id: string): T;
     function setSystemTime(now?: number | Date): void;
     function setTimeout(milliseconds: number): void;
     function useFakeTimers(options?: { now?: number | Date } | "modern" | "legacy"): typeof vi;