From 2e3c47bbd7603faa08254899049c1a4b9139c1ba Mon Sep 17 00:00:00 2001
From: Satoshi Qazi Muhammed <info@pezkuwichain.io>
Date: Sat, 10 Oct 2026 08:42:29 +0400
Subject: [PATCH] run-test: pass --experimental-test-module-mocks through to
 node

Specs that replace a module need mock.module from node:test, which
Node only exposes behind this flag. The runner rejected unknown flags,
so there was no way to turn it on. It is now accepted and forwarded to
node like --import and --require.

The repo's own test run enables it, and a spec checks that a module
registered as a mock is what a later dynamic import receives.
---
 package.json                                  |  2 +-
 packages/dev-test/src/env/moduleMocks.spec.ts | 14 ++++++++++++++
 packages/dev/README.md                        |  5 +++++
 packages/dev/scripts/pezkuwi-dev-run-test.mjs |  5 +++++
 4 files changed, 25 insertions(+), 1 deletion(-)
 create mode 100644 packages/dev-test/src/env/moduleMocks.spec.ts

diff --git a/package.json b/package.json
index bb88130..d0caa8f 100644
--- a/package.json
+++ b/package.json
@@ -30,7 +30,7 @@
     "docs": "pezkuwi-dev-build-docs",
     "lint": "pezkuwi-dev-run-lint",
     "postinstall": "./packages/dev/scripts/pezkuwi-dev-yarn-only.mjs",
-    "test": "yarn build && pezkuwi-dev-run-test --dev-build --env browser"
+    "test": "yarn build && pezkuwi-dev-run-test --dev-build --experimental-test-module-mocks --env browser"
   },
   "devDependencies": {
     "@pezkuwi/dev": "workspace:packages/dev",
diff --git a/packages/dev-test/src/env/moduleMocks.spec.ts b/packages/dev-test/src/env/moduleMocks.spec.ts
new file mode 100644
index 0000000..c4fb1b6
--- /dev/null
+++ b/packages/dev-test/src/env/moduleMocks.spec.ts
@@ -0,0 +1,14 @@
+// Copyright 2017-2026 @pezkuwi/dev-test authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import { mock } from 'node:test';
+
+describe('mock.module', () => {
+  it('replaces a module loaded after the mock is registered', async () => {
+    mock.module('node:os', { namedExports: { platform: () => 'mocked' } });
+
+    const { platform } = await import('node:os');
+
+    expect(platform()).toBe('mocked');
+  });
+});
diff --git a/packages/dev/README.md b/packages/dev/README.md
index 4038350..c0d1d7d 100644
--- a/packages/dev/README.md
+++ b/packages/dev/README.md
@@ -252,6 +252,11 @@ This script runs test files in the repository, filtering by file extensions and
 - **`--logfile <file>`**:  
   Specifies a log file to capture test output.
 
+- **`--experimental-test-module-mocks`**:  
+  Passed to Node.js, enabling `mock.module` from `node:test`. Node only swaps a module that has not
+  been loaded yet, so a spec registers its mocks first and then loads the code under test with a
+  dynamic `import()`.
+
 - **`--import <module>`**:  
   Imports the specified module.
 
diff --git a/packages/dev/scripts/pezkuwi-dev-run-test.mjs b/packages/dev/scripts/pezkuwi-dev-run-test.mjs
index 0e2878a..9e45fa5 100755
--- a/packages/dev/scripts/pezkuwi-dev-run-test.mjs
+++ b/packages/dev/scripts/pezkuwi-dev-run-test.mjs
@@ -58,6 +58,11 @@ for (let i = 0; i < args.length; i++) {
       cmd.push(args[++i]);
       break;
 
+    // node flags with no params
+    case '--experimental-test-module-mocks':
+      nodeFlags.push(args[i]);
+      break;
+
     // node flags that could have additional params
     case '--import':
     case '--loader':