test_runner: add mock file system API

Add t.mock.fs(): an in-memory mock file system backed by a mounted
virtual file system. The mock lives at a reserved mount point exposed
as mountPoint, so it never shadows real files, and it is unmounted
automatically when the test finishes.

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Author: mcollina

doc/api/test.md

@@ -2331,6 +2331,89 @@ This function is used to customize the location of the snapshot file used for
 snapshot testing. By default, the snapshot filename is the same as the entry
 point filename with a `.snapshot` file extension.
 
+## Class: `MockFSContext`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+The `MockFSContext` class is returned by [`mock.fs()`][] and is used to
+inspect and extend a mock file system.
+
+### `mockFs.addDirectory(path)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string} The path of the directory, relative to the mount point.
+* Returns: {string} The absolute path of the created directory.
+
+Adds a directory to the mock file system. Missing parent directories are
+created automatically.
+
+### `mockFs.addFile(path, content)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string} The path of the file, relative to the mount point.
+* `content` {string|Buffer|TypedArray|DataView} The file content.
+* Returns: {string} The absolute path of the created file.
+
+Adds a file to the mock file system. Missing parent directories are
+created automatically.
+
+### `mockFs.existsSync(path)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string} The path to check, relative to the mount point.
+* Returns: {boolean}
+
+Returns `true` if the path exists in the mock file system, and `false`
+otherwise, including once the mock has been restored.
+
+### `mockFs.mountPoint`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {string|null}
+
+The absolute path where the mock file system is mounted, or `null` once
+the mock has been restored. The mount point is a reserved path assigned
+by the [virtual file system][] when the mock is created; it never
+shadows real files or directories. Join it with relative paths to access
+the mock's files through the `node:fs` APIs.
+
+### `mockFs.restore()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Unmounts the mock file system. Once restored, the mock's files are no
+longer accessible and files can no longer be added. Calling this
+function more than once has no effect. This function is called
+automatically when the associated test finishes.
+
+### `mockFs.vfs`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {VirtualFileSystem}
+
+The underlying [`VirtualFileSystem`][] instance.
+
 ## Class: `MockFunctionContext`
 
 <!-- YAML
@@ -2658,6 +2741,64 @@ test('mocks a counting function', (t) => {
 });
 ```
 
+### `mock.fs([options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+* `options` {Object} Optional configuration options for the mock file
+  system. The following properties are supported:
+  * `files` {Object} Initial files to create. Keys are file paths relative
+    to the mount point, and values are the file contents as {string} or
+    {Buffer}. Missing parent directories are created automatically.
+* Returns: {MockFSContext} An object that can be used to manage the mock
+  file system.
+
+This function creates an in-memory mock file system backed by the
+[virtual file system][]. The mock is mounted at a reserved mount point
+that is assigned when the mock is created and exposed as
+[`mockFs.mountPoint`][], so it never shadows real files or directories.
+Paths obtained by joining the mount point with a relative path work with
+the regular `node:fs` APIs and can be loaded with `require()` and
+`import`.
+
+If this function is invoked through a `TestContext`, the mock file
+system is unmounted automatically when the test finishes.
+
+```js
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+test('reads configuration from a mock file', (t) => {
+  const mockFs = t.mock.fs({
+    files: {
+      'config.json': JSON.stringify({ debug: true }),
+      'data/users.txt': 'user1\nuser2\nuser3',
+    },
+  });
+
+  // Files are accessible via standard fs APIs under the mount point.
+  const configPath = path.join(mockFs.mountPoint, 'config.json');
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  assert.strictEqual(config.debug, true);
+
+  // Files can be added after creation. addFile() returns the
+  // absolute path of the new file.
+  const readmePath = mockFs.addFile('README.md', '# Hello');
+  assert.strictEqual(fs.readFileSync(readmePath, 'utf8'), '# Hello');
+
+  // Modules in the mock file system can be loaded with require()
+  // and import.
+  const modPath = mockFs.addFile('mod.js', 'module.exports = 42;');
+  assert.strictEqual(require(modPath), 42);
+});
+```
+
 ### `mock.getter(object, methodName[, implementation][, options])`
 
 <!-- YAML
@@ -5035,6 +5176,7 @@ test.describe('my suite', (suite) => {
 [`SuiteContext`]: #class-suitecontext
 [`TestContext`]: #class-testcontext
 [`TracingChannel`]: diagnostics_channel.md#class-tracingchannel
+[`VirtualFileSystem`]: vfs.md#class-virtualfilesystem
 [`assert.throws`]: assert.md#assertthrowsfn-error-message
 [`context.diagnostic`]: #contextdiagnosticmessage
 [`context.log`]: #contextlogmessage-data
@@ -5045,6 +5187,8 @@ test.describe('my suite', (suite) => {
 [`diagnostics_channel`]: diagnostics_channel.md
 [`glob(7)`]: https://man7.org/linux/man-pages/man7/glob.7.html
 [`it()`]: #itname-options-fn
+[`mock.fs()`]: #mockfsoptions
+[`mockFs.mountPoint`]: #mockfsmountpoint
 [`run()`]: #runoptions
 [`suite()`]: #suitename-options-fn
 [`test()`]: #testname-options-fn
@@ -5059,3 +5203,4 @@ test.describe('my suite', (suite) => {
 [suite options]: #suitename-options-fn
 [test reporters]: #test-reporters
 [test runner execution model]: #test-runner-execution-model
+[virtual file system]: vfs.md

doc/api/vfs.md

@@ -450,6 +450,12 @@ The SEA configuration parser will error if either combination is detected.
 See the [Single Executable Application][] documentation for more information
 on creating SEA builds with assets.
 
+## Use with the test runner
+
+The [`mock.fs()`][] API of the `node:test` module creates a mock file
+system backed by a mounted `VirtualFileSystem`, which is unmounted
+automatically when the associated test finishes.
+
 ## Class: `VirtualProvider`
 
 <!-- YAML
@@ -631,6 +637,7 @@ fields use synthetic but stable values:
 [`fs.BigIntStats`]: fs.md#class-fsstats
 [`fs.Stats`]: fs.md#class-fsstats
 [`import.meta.resolve()`]: esm.md#importmetaresolvespecifier
+[`mock.fs()`]: test.md#mockfsoptions
 [`node:fs`]: fs.md
 [`require()`]: modules.md#requireid
 [`require.resolve()`]: modules.md#requireresolverequest-options

lib/internal/test_runner/mock/mock.js

@@ -54,8 +54,11 @@ const {
   validateInteger,
   validateObject,
   validateOneOf,
+  validateString,
 } = require('internal/validators');
 const { MockTimers } = require('internal/test_runner/mock/mock_timers');
+const { isArrayBufferView } = require('internal/util/types');
+const { dirname, join } = require('path');
 const {
   Module,
 } = require('internal/modules/cjs/loader');
@@ -449,6 +452,103 @@ class MockPropertyContext {
 
 const { restore: restoreProperty } = MockPropertyContext.prototype;
 
+/**
+ * Context for a mock file system backed by a mounted virtual file
+ * system. Returned by MockTracker.fs().
+ */
+class MockFSContext {
+  #vfs;
+
+  constructor(vfs) {
+    this.#vfs = vfs;
+  }
+
+  /**
+   * The underlying VirtualFileSystem instance.
+   * @type {VirtualFileSystem}
+   */
+  get vfs() {
+    return this.#vfs;
+  }
+
+  /**
+   * The mount point of the mock file system, or null once restored.
+   * @type {string|null}
+   */
+  get mountPoint() {
+    return this.#vfs.mountPoint;
+  }
+
+  #resolve(filePath) {
+    validateString(filePath, 'path');
+    const mountPoint = this.#vfs.mountPoint;
+    if (mountPoint === null) {
+      throw new ERR_INVALID_STATE('The mock file system has been restored');
+    }
+    return join(mountPoint, filePath);
+  }
+
+  /**
+   * Adds a file to the mock file system, creating parent directories
+   * as needed.
+   * @param {string} filePath - The path of the file, relative to the mount
+   *   point.
+   * @param {string|Buffer} content - The file content.
+   * @returns {string} The absolute path of the created file.
+   */
+  addFile(filePath, content) {
+    const fullPath = this.#resolve(filePath);
+    if (typeof content !== 'string' && !isArrayBufferView(content)) {
+      throw new ERR_INVALID_ARG_TYPE(
+        'content', ['string', 'Buffer', 'TypedArray', 'DataView'], content,
+      );
+    }
+    const parentDir = dirname(fullPath);
+    if (parentDir !== this.#vfs.mountPoint) {
+      this.#vfs.mkdirSync(parentDir, { __proto__: null, recursive: true });
+    }
+    this.#vfs.writeFileSync(fullPath, content);
+    return fullPath;
+  }
+
+  /**
+   * Adds a directory to the mock file system, creating parent
+   * directories as needed.
+   * @param {string} dirPath - The path of the directory, relative to the
+   *   mount point.
+   * @returns {string} The absolute path of the created directory.
+   */
+  addDirectory(dirPath) {
+    const fullPath = this.#resolve(dirPath);
+    this.#vfs.mkdirSync(fullPath, { __proto__: null, recursive: true });
+    return fullPath;
+  }
+
+  /**
+   * Checks if a path exists in the mock file system.
+   * @param {string} filePath - The path to check, relative to the mount
+   *   point.
+   * @returns {boolean}
+   */
+  existsSync(filePath) {
+    if (this.#vfs.mountPoint === null) {
+      return false;
+    }
+    return this.#vfs.existsSync(this.#resolve(filePath));
+  }
+
+  /**
+   * Unmounts the mock file system.
+   */
+  restore() {
+    if (this.#vfs.mounted) {
+      this.#vfs.unmount();
+    }
+  }
+}
+
+const { restore: restoreFileSystem } = MockFSContext.prototype;
+
 class MockTracker {
   #mocks = [];
   #timers;
@@ -493,6 +593,45 @@ class MockTracker {
     return this.#setupMock(ctx, original);
   }
 
+  /**
+   * Creates a mock file system backed by a mounted virtual file system.
+   * @param {object} [options] - Options for the mock file system.
+   * @param {object} [options.files] - Initial files to create. Keys are file
+   *   paths relative to the mount point and values are the file contents.
+   * @returns {MockFSContext} The mock file system context.
+   */
+  fs(options = kEmptyObject) {
+    emitExperimentalWarning('The mock.fs API');
+    validateObject(options, 'options');
+    const { files } = options;
+    if (files !== undefined) {
+      validateObject(files, 'options.files');
+    }
+
+    const { VirtualFileSystem } = require('internal/vfs/file_system');
+    const vfs = new VirtualFileSystem({
+      __proto__: null,
+      emitExperimentalWarning: false,
+    });
+    vfs.mount();
+    const ctx = new MockFSContext(vfs);
+
+    if (files !== undefined) {
+      const paths = ObjectKeys(files);
+      for (let i = 0; i < paths.length; i++) {
+        ctx.addFile(paths[i], files[paths[i]]);
+      }
+    }
+
+    ArrayPrototypePush(this.#mocks, {
+      __proto__: null,
+      ctx,
+      restore: restoreFileSystem,
+    });
+
+    return ctx;
+  }
+
   /**
    * Creates a method tracker for a specified object or function.
    * @param {(object | Function)} objectOrFunction - The object or function containing the method to be tracked.