test_runner: add experimental `mock.fs` API #61468

sozua · 2026-01-22T05:38:30Z

Add experimental mock.fs API to the test runner for mocking file system operations in tests. This allows tests to simulate file operations without actually reading from or writing to disk.

Note: There is an existing draft PR #59194 by @joaoGabriel55 working on this feature, though it appears to have stalled (last updated August 2025). This implementation takes a different approach based on maintainer feedback in the issue discussion:

Uses mock.fs naming as suggested by @MoLow
Gated behind --experimental-test-fs-mocks flag as suggested by @ljharb
Includes callback and promise variants, not just sync methods

Features

Virtual file system with string, Buffer, or Uint8Array content
Supports sync, callback, and promise variants of fs APIs
Mocked APIs: readFile, writeFile, appendFile, stat, lstat, access, exists, unlink, mkdir, rmdir, readdir
Isolation mode (isolate: true) to completely block real filesystem access
Selective API mocking via the apis option
Write operations always go to virtual fs (prevents accidental disk writes)
Symbol.dispose support for automatic cleanup

Examples

Basic usage

import { test } from 'node:test';
import fs from 'node:fs';
import assert from 'node:assert';

test('mock file system', (t) => {
  t.mock.fs.enable({
    files: {
      '/virtual/config.json': '{"key": "value"}',
    },
  });

  const config = JSON.parse(fs.readFileSync('/virtual/config.json', 'utf8'));
  assert.strictEqual(config.key, 'value');
});

Isolation mode

test('complete isolation from real filesystem', (t) => {
  t.mock.fs.enable({
    files: {
      '/virtual/only.txt': 'isolated content',
    },
    isolate: true,
  });

  // Virtual file works
  assert.strictEqual(fs.readFileSync('/virtual/only.txt', 'utf8'), 'isolated content');

  // Real files are blocked
  assert.throws(() => fs.readFileSync('/etc/passwd'), { code: 'ENOENT' });
});

Write operations

test('writes always go to virtual fs', (t) => {
  t.mock.fs.enable({ files: {} });

  // Write to virtual fs
  fs.writeFileSync('/tmp/test.txt', 'safe write');

  // Read it back
  assert.strictEqual(fs.readFileSync('/tmp/test.txt', 'utf8'), 'safe write');

  // After test ends, nothing written to real /tmp
});

Async/promises

import fsPromises from 'node:fs/promises';

test('works with promises', async (t) => {
  t.mock.fs.enable({
    files: { '/data/file.txt': 'async content' },
  });

  const content = await fsPromises.readFile('/data/file.txt', 'utf8');
  assert.strictEqual(content, 'async content');
});

Directory operations

test('directory operations', (t) => {
  t.mock.fs.enable({
    files: {
      '/app/src/index.js': 'console.log("hello")',
      '/app/src/utils.js': 'export default {}',
    },
  });

  const entries = fs.readdirSync('/app/src');
  assert.deepStrictEqual(entries.sort(), ['index.js', 'utils.js']);
});

Next Steps

This PR provides an initial set of commonly-used fs operations. Future iterations could add file operations like rename, copyFile, rm, and truncate, as well as symlink support (symlink, readlink, link).

Refs: #55902

nodejs-github-bot · 2026-01-22T05:38:36Z

Review requested:

@nodejs/config
@nodejs/test_runner

lib/internal/test_runner/mock/mock_file_system.js

ljharb · 2026-01-22T06:10:28Z

lib/internal/test_runner/mock/mock_file_system.js

+ * @enum {('readFile'|'writeFile'|'appendFile'|'stat'|'lstat'|'access'|
+ *   'exists'|'unlink'|'mkdir'|'rmdir'|'readdir')[]} Supported fs APIs
+ */
+const SUPPORTED_APIS = [


what are the unsupported ones? is the plan to support them gradually?

rename, copyFile, rm, symlinks, etc. There is a lot of other operations from fs that arent included in here. And yes, I plan to support all of them gradually, although I think the operations in this iteration looks fine for the initial scope

lib/internal/test_runner/mock/mock_file_system.js

codecov · 2026-01-22T07:43:37Z

Codecov Report

❌ Patch coverage is 86.75388% with 162 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.83%. Comparing base (95852d7) to head (c12a9b7).
⚠️ Report is 133 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/test_runner/mock/mock_file_system.js	86.52%	160 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #61468      +/-   ##
==========================================
+ Coverage   88.54%   89.83%   +1.28%     
==========================================
  Files         704      672      -32     
  Lines      208753   204401    -4352     
  Branches    40280    39272    -1008     
==========================================
- Hits       184847   183621    -1226     
+ Misses      15907    13125    -2782     
+ Partials     7999     7655     -344

Files with missing lines	Coverage Δ
lib/internal/test_runner/mock/mock.js	`98.75% <100.00%> (+0.02%)`	⬆️
src/node_options.cc	`77.92% <100.00%> (+0.12%)`	⬆️
src/node_options.h	`97.89% <100.00%> (ø)`
lib/internal/test_runner/mock/mock_file_system.js	`86.52% <86.52%> (ø)`

... and 136 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

pmarchini · 2026-01-22T09:10:21Z

Thanks for the contribution! I will take a look ASAP, though I think it would be great to have a review from @nodejs/fs as well.

I'm also wondering if it might make sense to break down this PR into even more granular iterations, as it's already a non-trivial change!

@nodejs/test_runner any thoughts?

sozua · 2026-01-22T09:24:59Z

Thanks @ljharb for the comment, really appreciate it! There was a lot of interesting stuff I learned while reviewing your questions. Some of them should already be resolved, while I'll resolve/comment on the others ASAP.

@pmarchini thanks and I think that makes total sense. In issue #55902, we already exchanged some ideas about this. I think it makes sense to centralize that discussion there, what do you think? Either way, I'm happy to close this PR and work it based on the chosen scope and granularity, if necessary!

github-actions · 2026-01-22T11:31:58Z

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @avivkeller.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

doc/api/test.md

avivkeller · 2026-01-22T11:37:24Z

doc/api/test.md

+| Property                                    | Type     | Default                          |
+| ------------------------------------------- | -------- | -------------------------------- |
+| `dev`                                       | `number` | `0`                              |
+| `ino`                                       | `number` | `0`                              |
+| `mode`                                      | `number` | File: `0o100644`, Dir: `0o40644` |
+| `nlink`                                     | `number` | `1`                              |
+| `uid`                                       | `number` | `0`                              |
+| `gid`                                       | `number` | `0`                              |
+| `rdev`                                      | `number` | `0`                              |
+| `size`                                      | `number` | Content length                   |
+| `blksize`                                   | `number` | `4096`                           |
+| `blocks`                                    | `number` | `ceil(size / 512)`               |
+| `atime`/`mtime`/`ctime`/`birthtime`         | `Date`   | Creation time                    |
+| `atimeMs`/`mtimeMs`/`ctimeMs`/`birthtimeMs` | `number` | Creation time (ms)               |


I wonder, and perhaps this is too much for a single PR, if these should be mock-able.

{ files: { myFilePath: 'content', myOtherFile: { atime: 123, content: 'some data' }, } }

avivkeller · 2026-01-22T11:39:36Z

lib/internal/test_runner/mock/mock_file_system.js

+const { call: FunctionCall, bind: FunctionBind } = Function.prototype;
+const BufferPrototypeToString = FunctionCall.call(FunctionBind, FunctionCall, Buffer.prototype.toString);
+const BufferFrom = Buffer.from;
+const BufferConcat = Buffer.concat;
+const BufferAlloc = Buffer.alloc;


Don't we have these in primordials?

lib/internal/test_runner/mock/mock_file_system.js

avivkeller · 2026-01-22T11:45:04Z

lib/internal/test_runner/mock/mock_file_system.js

+/**
+ * @param {string} syscall
+ * @param {string} filepath
+ * @returns {Error}
+ */
+function createENOENT(syscall, filepath) {
+  return new UVException({
+    __proto__: null,
+    errno: UV_ENOENT,
+    syscall,
+    path: filepath,
+    message: 'no such file or directory',
+  });
+}
+
+/**
+ * @param {string} syscall
+ * @param {string} filepath
+ * @returns {Error}
+ */
+function createENOTDIR(syscall, filepath) {
+  return new UVException({
+    __proto__: null,
+    errno: UV_ENOTDIR,
+    syscall,
+    path: filepath,
+    message: 'not a directory',
+  });
+}
+
+/**
+ * @param {string} syscall
+ * @param {string} filepath
+ * @returns {Error}
+ */
+function createENOTEMPTY(syscall, filepath) {
+  return new UVException({
+    __proto__: null,
+    errno: UV_ENOTEMPTY,
+    syscall,
+    path: filepath,
+    message: 'directory not empty',
+  });
+}
+
+/**
+ * @param {string} syscall
+ * @param {string} filepath
+ * @returns {Error}
+ */
+function createEEXIST(syscall, filepath) {
+  return new UVException({
+    __proto__: null,
+    errno: UV_EEXIST,
+    syscall,
+    path: filepath,
+    message: 'file already exists',
+  });
+}
+
+/**
+ * @param {string} syscall
+ * @param {string} filepath
+ * @returns {Error}
+ */
+function createEISDIR(syscall, filepath) {
+  return new UVException({
+    __proto__: null,
+    errno: UV_EISDIR,
+    syscall,
+    path: filepath,
+    message: 'illegal operation on a directory',
+  });
+}


A few notes on these functions:

Perhaps I missed some usages, but these functions are only called once, do they need to be functions?

We need to ensure that these error messages line up with fs's. Can we add a test to validate that?

lib/internal/test_runner/mock/mock_file_system.js

ljharb · 2026-01-22T19:33:49Z

Should perhaps this PR wait on #61478, and use it as the mock implementation?

sozua · 2026-01-23T18:54:58Z

I'll be closing this PR to avoid polluting the PR list, since #61478 includes the mock in its scope and, IMO, uses a more elegant approach.

I'll also be watching the comments on this PR and on the original issue, in case this work can be useful in the future or help the project in any way.

Thank you @ljharb and @avivkeller for taking the time to review the changes.

JakobJingleheimer · 2026-01-23T19:43:21Z

Thank you @sozua. This happens to even collaborators :(

sozua added 2 commits January 22, 2026 00:57

test_runner: add mock file system support

581475d

doc: document mock file system for test runner

c12a9b7

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jan 22, 2026

ljharb reviewed Jan 22, 2026

View reviewed changes

sozua added 2 commits January 22, 2026 04:51

doc: add --experimental-test-fs-mocks to manpage and fix option order

9d3ed17

test_runner: address review feedback for mock file system

5e8e835

test_runner: use call-bind pattern for BufferPrototypeToString

93226ab

avivkeller added semver-minor PRs that contain new features and should be released in the next minor version. notable-change PRs with changes that should be highlighted in changelogs. test_runner Issues and PRs related to the test runner subsystem. labels Jan 22, 2026

avivkeller reviewed Jan 22, 2026

View reviewed changes

test_runner: use uncurryThis for BufferPrototypeToString

502e48b

sozua added 2 commits January 23, 2026 00:46

test_runner: use path.join and ObjectDefineProperty in mock fs

f921730

test_runner: refactor mock fs stats and error handling

8fd61d7

sozua closed this Jan 23, 2026

Uh oh!

test_runner: add experimental mock.fs API #61468

test_runner: add experimental mock.fs API #61468

Conversation

sozua commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Features

Examples

Next Steps

Uh oh!

nodejs-github-bot commented Jan 22, 2026

Uh oh!

Uh oh!

ljharb Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

sozua Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pmarchini commented Jan 22, 2026

Uh oh!

sozua commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 22, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

avivkeller Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

avivkeller Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

avivkeller Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ljharb commented Jan 22, 2026

Uh oh!

sozua commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JakobJingleheimer commented Jan 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

test_runner: add experimental `mock.fs` API #61468

test_runner: add experimental `mock.fs` API #61468

sozua commented Jan 22, 2026 •

edited

Loading

codecov bot commented Jan 22, 2026 •

edited

Loading

sozua commented Jan 22, 2026 •

edited

Loading

sozua commented Jan 23, 2026 •

edited

Loading