test_runner: add mock.fs() for file system mocking

Add mock.fs() API to the test runner's MockTracker class, enabling
tests to create isolated virtual file systems without touching disk.

Features:
- t.mock.fs({ prefix, files }) creates a mock file system
- Files accessible via standard fs APIs (readFileSync, existsSync, etc.)
- Supports require() from virtual files
- Supports dynamic file content via functions
- Automatic cleanup when test completes
- Multiple mock instances can coexist

Also adds fs.existsSync hook to VFS module_hooks.js to properly
intercept existence checks for virtual files.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: mcollina

doc/api/test.md

@@ -2334,6 +2334,92 @@ 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:
+  * `prefix` {string} The mount point prefix for the virtual file system.
+    **Default:** `'/mock'`.
+  * `files` {Object} An optional object where keys are file paths (relative to
+    the VFS root) and values are the file contents. Contents can be strings,
+    Buffers, or functions that return strings/Buffers.
+* Returns: {MockFSContext} An object that can be used to manage the mock file
+  system.
+
+This function creates a mock file system using the Virtual File System (VFS).
+The mock file system is automatically cleaned up when the test completes.
+
+The returned `MockFSContext` object provides the following methods and
+properties:
+
+* `vfs` {VirtualFileSystem} The underlying VFS instance.
+* `prefix` {string} The mount prefix.
+* `addFile(path, content)` Adds a file to the mock file system.
+* `addDirectory(path[, populate])` Adds a directory to the mock file system.
+* `existsSync(path)` Checks if a path exists (path is relative to prefix).
+* `restore()` Manually restores the file system to its original state.
+
+The following example demonstrates how to create a mock file system for testing:
+
+```js
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+
+test('reads configuration from mock file', (t) => {
+  const mockFs = t.mock.fs({
+    prefix: '/app',
+    files: {
+      '/config.json': JSON.stringify({ debug: true }),
+      '/data/users.txt': 'user1\nuser2\nuser3',
+    },
+  });
+
+  // Files are accessible via standard fs APIs
+  const config = JSON.parse(fs.readFileSync('/app/config.json', 'utf8'));
+  assert.strictEqual(config.debug, true);
+
+  // Check file existence
+  assert.strictEqual(fs.existsSync('/app/config.json'), true);
+  assert.strictEqual(fs.existsSync('/app/missing.txt'), false);
+
+  // Use mockFs.existsSync for paths relative to prefix
+  assert.strictEqual(mockFs.existsSync('/config.json'), true);
+});
+
+test('supports dynamic file content', (t) => {
+  let counter = 0;
+  const mockFs = t.mock.fs({ prefix: '/dynamic' });
+
+  mockFs.addFile('/counter.txt', () => {
+    counter++;
+    return String(counter);
+  });
+
+  // Each read calls the function
+  assert.strictEqual(fs.readFileSync('/dynamic/counter.txt', 'utf8'), '1');
+  assert.strictEqual(fs.readFileSync('/dynamic/counter.txt', 'utf8'), '2');
+});
+
+test('supports require from mock files', (t) => {
+  t.mock.fs({
+    prefix: '/modules',
+    files: {
+      '/math.js': 'module.exports = { add: (a, b) => a + b };',
+    },
+  });
+
+  const math = require('/modules/math.js');
+  assert.strictEqual(math.add(2, 3), 5);
+});
+```
+
 ### `mock.getter(object, methodName[, implementation][, options])`
 
 <!-- YAML

lib/internal/test_runner/mock/mock.js

@@ -402,6 +402,73 @@ class MockPropertyContext {
 
 const { restore: restoreProperty } = MockPropertyContext.prototype;
 
+/**
+ * Context for mocking the file system using VFS.
+ */
+class MockFSContext {
+  #vfs;
+  #prefix;
+
+  constructor(vfs, prefix) {
+    this.#vfs = vfs;
+    this.#prefix = prefix;
+  }
+
+  /**
+   * Gets the underlying VirtualFileSystem instance.
+   * @returns {VirtualFileSystem}
+   */
+  get vfs() {
+    return this.#vfs;
+  }
+
+  /**
+   * Gets the mount prefix for the mock file system.
+   * @returns {string}
+   */
+  get prefix() {
+    return this.#prefix;
+  }
+
+  /**
+   * Adds a file to the mock file system.
+   * @param {string} path - The path of the file.
+   * @param {string|Buffer|Function} content - The file content.
+   */
+  addFile(path, content) {
+    this.#vfs.addFile(path, content);
+  }
+
+  /**
+   * Adds a directory to the mock file system.
+   * @param {string} path - The path of the directory.
+   * @param {Function} [populate] - Optional callback to populate the directory.
+   */
+  addDirectory(path, populate) {
+    this.#vfs.addDirectory(path, populate);
+  }
+
+  /**
+   * Checks if a path exists in the mock file system.
+   * @param {string} path - The path to check (relative to prefix).
+   * @returns {boolean}
+   */
+  existsSync(path) {
+    // Prepend prefix to path for VFS lookup
+    const fullPath = this.#prefix + (StringPrototypeStartsWith(path, '/') ? path : '/' + path);
+    return this.#vfs.existsSync(fullPath);
+  }
+
+  /**
+   * Restores the file system to its original state.
+   */
+  restore() {
+    this.#vfs.unmount();
+  }
+}
+
+const { restore: restoreFS } = MockFSContext.prototype;
+
 class MockTracker {
   #mocks = [];
   #timers;
@@ -725,6 +792,45 @@ class MockTracker {
     });
   }
 
+  /**
+   * Creates a mock file system using VFS.
+   * @param {object} [options] - Options for the mock file system.
+   * @param {string} [options.prefix='/mock'] - The mount prefix for the VFS.
+   * @param {object} [options.files] - Initial files to add (path: content pairs).
+   * @returns {MockFSContext} The mock file system context.
+   */
+  fs(options = kEmptyObject) {
+    validateObject(options, 'options');
+    const { prefix = '/mock', files } = options;
+    if (files !== undefined) {
+      validateObject(files, 'options.files');
+    }
+
+    const { VirtualFileSystem } = require('internal/vfs/virtual_fs');
+    const vfs = new VirtualFileSystem({ moduleHooks: true });
+
+    // Add initial files if provided
+    if (files) {
+      const paths = ObjectKeys(files);
+      for (let i = 0; i < paths.length; i++) {
+        const path = paths[i];
+        vfs.addFile(path, files[path]);
+      }
+    }
+
+    // Mount the VFS at the specified prefix
+    vfs.mount(prefix);
+
+    const ctx = new MockFSContext(vfs, prefix);
+    ArrayPrototypePush(this.#mocks, {
+      __proto__: null,
+      ctx,
+      restore: restoreFS,
+    });
+
+    return ctx;
+  }
+
   /**
    * Resets the mock tracker, restoring all mocks and clearing timers.
    */

lib/internal/vfs/module_hooks.js

@@ -27,6 +27,8 @@ let originalLstatSync = null;
 let originalStatSync = null;
 // Original fs.readdirSync function
 let originalReaddirSync = null;
+// Original fs.existsSync function
+let originalExistsSync = null;
 // Original fs/promises.readdir function
 let originalPromisesReaddir = null;
 // Original fs/promises.lstat function
@@ -123,6 +125,27 @@ function findVFSForRead(filename, options) {
   return null;
 }
 
+/**
+ * Checks all active VFS instances for existence.
+ * @param {string} filename The absolute path to check
+ * @returns {{ vfs: VirtualFileSystem, exists: boolean }|null}
+ */
+function findVFSForExists(filename) {
+  const normalized = normalizePath(filename);
+  for (let i = 0; i < activeVFSList.length; i++) {
+    const vfs = activeVFSList[i];
+    if (vfs.shouldHandle(normalized)) {
+      // For mounted VFS, we handle the path (return exists result)
+      // For overlay VFS, we only handle if it exists in VFS
+      const exists = vfs.existsSync(normalized);
+      if (vfs.isMounted || exists) {
+        return { vfs, exists };
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Checks all active VFS instances for realpath.
  * @param {string} filename The path to resolve
@@ -500,6 +523,19 @@ function installHooks() {
     return originalReaddirSync.call(fs, path, options);
   };
 
+  // Override fs.existsSync
+  originalExistsSync = fs.existsSync;
+  fs.existsSync = function vfsExistsSync(path) {
+    if (typeof path === 'string' || path instanceof URL) {
+      const pathStr = typeof path === 'string' ? path : path.pathname;
+      const vfsResult = findVFSForExists(pathStr);
+      if (vfsResult !== null) {
+        return vfsResult.exists;
+      }
+    }
+    return originalExistsSync.call(fs, path);
+  };
+
   // Hook fs/promises for async glob support
   const fsPromises = require('fs/promises');