[node] test: mock.module can take a URL

This behavior is since nodejs/node#54416. It is in v22 since v22.8.0 (nodejs/node#54560), v24 since v24.0.0, and v25 since v25.0.0. It's not in v22.

Relevant Nodejs docs: https://nodejs.org/docs/latest-v25.x/api/test.html#mockmodulespecifier-options

Relevant Nodejs code: https://github.com/nodejs/node/blob/ae2ffce5f3d5ac5ad153d98839d5a19a70e073b2/lib/internal/test_runner/mock/mock.js#L619-L625

Relevant Nodejs test: https://github.com/nodejs/node/blob/ae2ffce5f3d5ac5ad153d98839d5a19a70e073b2/test/parallel/test-runner-module-mocking.js#L158-L160

Author: reillylm

types/node/node-tests/test.ts

@@ -20,6 +20,7 @@ import {
     todo,
 } from "node:test";
 import { dot, junit, lcov, spec, tap, TestEvent } from "node:test/reporters";
+import { URL } from "node:url";
 
 // top-level export
 test satisfies typeof import("node:test");
@@ -795,6 +796,7 @@ test("mocks a setter", (t) => {
 });
 
 test("mocks a module", (t) => {
+    // module specifier as a string
     // $ExpectType MockModuleContext
     const mock = t.mock.module("node:readline", {
         namedExports: {
@@ -811,6 +813,16 @@ test("mocks a module", (t) => {
     });
     // $ExpectType void
     mock.restore();
+
+    // module specifier as a URL
+    // $ExpectType MockModuleContext
+    t.mock.module(new URL("someUrl"), {
+        namedExports: {
+            fn() {
+                return 42;
+            },
+        },
+    });
 });
 
 test("mocks a property", (t) => {

types/node/test.d.ts

@@ -82,6 +82,7 @@ declare module "node:test" {
     import { AssertMethodNames } from "node:assert";
     import { Readable, ReadableEventMap } from "node:stream";
     import { TestEvent } from "node:test/reporters";
+    import { URL } from "node:url";
     import TestFn = test.TestFn;
     import TestOptions = test.TestOptions;
     /**
@@ -1692,7 +1693,7 @@ declare module "node:test" {
              * @param specifier A string identifying the module to mock.
              * @param options Optional configuration options for the mock module.
              */
-            module(specifier: string, options?: MockModuleOptions): MockModuleContext;
+            module(specifier: string | URL, options?: MockModuleOptions): MockModuleContext;
             /**
              * Creates a mock for a property value on an object. This allows you to track and control access to a specific property,
              * including how many times it is read (getter) or written (setter), and to restore the original value after mocking.

types/node/v22/test.d.ts

@@ -81,6 +81,7 @@
 declare module "node:test" {
     import { AssertMethodNames } from "node:assert";
     import { Readable } from "node:stream";
+    import { URL } from "node:url";
     import TestFn = test.TestFn;
     import TestOptions = test.TestOptions;
     /**
@@ -1638,7 +1639,7 @@ declare module "node:test" {
              * @param specifier A string identifying the module to mock.
              * @param options Optional configuration options for the mock module.
              */
-            module(specifier: string, options?: MockModuleOptions): MockModuleContext;
+            module(specifier: string | URL, options?: MockModuleOptions): MockModuleContext;
             /**
              * This function restores the default behavior of all mocks that were previously
              * created by this `MockTracker` and disassociates the mocks from the `MockTracker` instance. Once disassociated, the mocks can still be used, but the `MockTracker` instance can no longer be

types/node/v22/test/test.ts

@@ -20,6 +20,7 @@ import {
     todo,
 } from "node:test";
 import { dot, junit, lcov, spec, tap, TestEvent } from "node:test/reporters";
+import { URL } from "node:url";
 
 // top-level export
 test satisfies typeof import("node:test");
@@ -791,6 +792,7 @@ test("mocks a setter", (t) => {
 });
 
 test("mocks a module", (t) => {
+    // module specifier as a string
     // $ExpectType MockModuleContext
     const mock = t.mock.module("node:readline", {
         namedExports: {
@@ -807,6 +809,16 @@ test("mocks a module", (t) => {
     });
     // $ExpectType void
     mock.restore();
+
+    // module specifier as a URL
+    // $ExpectType MockModuleContext
+    t.mock.module(new URL("someUrl"), {
+        namedExports: {
+            fn() {
+                return 42;
+            },
+        },
+    });
 });
 
 // @ts-expect-error

types/node/v24/test.d.ts

@@ -81,6 +81,7 @@
 declare module "node:test" {
     import { AssertMethodNames } from "node:assert";
     import { Readable } from "node:stream";
+    import { URL } from "node:url";
     import TestFn = test.TestFn;
     import TestOptions = test.TestOptions;
     /**
@@ -1711,7 +1712,7 @@ declare module "node:test" {
              * @param specifier A string identifying the module to mock.
              * @param options Optional configuration options for the mock module.
              */
-            module(specifier: string, options?: MockModuleOptions): MockModuleContext;
+            module(specifier: string | URL, options?: MockModuleOptions): MockModuleContext;
             /**
              * Creates a mock for a property value on an object. This allows you to track and control access to a specific property,
              * including how many times it is read (getter) or written (setter), and to restore the original value after mocking.

types/node/v24/test/test.ts

@@ -20,6 +20,7 @@ import {
     todo,
 } from "node:test";
 import { dot, junit, lcov, spec, tap, TestEvent } from "node:test/reporters";
+import { URL } from "node:url";
 
 // top-level export
 test satisfies typeof import("node:test");
@@ -795,6 +796,7 @@ test("mocks a setter", (t) => {
 });
 
 test("mocks a module", (t) => {
+    // module specifier as a string
     // $ExpectType MockModuleContext
     const mock = t.mock.module("node:readline", {
         namedExports: {
@@ -811,6 +813,16 @@ test("mocks a module", (t) => {
     });
     // $ExpectType void
     mock.restore();
+
+    // module specifier as a URL
+    // $ExpectType MockModuleContext
+    t.mock.module(new URL("someUrl"), {
+        namedExports: {
+            fn() {
+                return 42;
+            },
+        },
+    });
 });
 
 test("mocks a property", (t) => {