Repository files navigation

Themock-fs module allows Node's built-infs module to be backed temporarily by an in-memory, mock file system. This lets you run tests against a set of mock files and directories instead of lugging around a bunch of test fixtures.

The code below makes it so thefs module is temporarily backed by a mock file system with a few files and directories.

constmock=require('mock-fs');mock({'path/to/fake/dir':{'some-file.txt':'file content here','empty-dir':{/** empty directory */}},'path/to/some.png':Buffer.from([8,6,7,5,3,0,9]),'some/other/path':{/** another empty directory */}});

When you are ready to restore thefs module (so that it is backed by your real file system), callmock.restore(). Note that calling this may bemandatory in some cases. Seeistanbuljs/nyc#324

// after a test runsmock.restore();

Instead of overriding all methods of the built-infs module, the library now overridesprocess.binding('fs'). The purpose of this change is to avoid conflicts with other libraries that overridefs methods (e.g.graceful-fs) and to make it possible to work with multiple Node releases without maintaining copied and slightly modified versions of Node'sfs module.

Breaking changes:

• Themock.fs() function has been removed. This returned an object withfs-like methods without overriding the built-infs module.
• The object created byfs.Stats is no longer an instance offs.Stats (though it has all the same properties and methods).
• Lazyrequire() do not use the real filesystem.
• Tests are no longer run in Node < 4.

Some of these breaking changes may be restored in a future release.

Configure thefs module so it is backed by an in-memory file system.

Callingmock sets up a mock file system with two directories by default:process.cwd() andos.tmpdir() (oros.tmpDir() for older Node). When called with no arguments, just these two directories are created. When called with aconfig object, additional files, directories, and symlinks are created. To avoid creating a directory forprocess.cwd() andos.tmpdir(), see theoptions below.

Property names of theconfig object are interpreted as relative paths to resources (relative fromprocess.cwd()). Property values of theconfig object are interpreted as content or configuration for the generated resources.

Note that paths should always use forward slashes (/) - even on Windows.

The second (optional) argument may include the properties below.

• createCwd -boolean Create a directory forprocess.cwd(). This istrue by default.
• createTmp -boolean Create a directory foros.tmpdir(). This istrue by default.

You can load real files and directories into the mock system usingmock.load()

• All stat information is duplicated (dates, permissions, etc)
• By default, all files are lazy-loaded, unless you specify the{lazy: false} option

mock({// Lazy-load file'my-file.txt':mock.load(path.resolve(__dirname,'assets/special-file.txt')),// Pre-load js file'ready.js':mock.load(path.resolve(__dirname,'scripts/ready.js'),{lazy:false}),// Recursively loads all node_modules'node_modules':mock.load(path.resolve(__dirname,'../node_modules')),// Creates a directory named /tmp with only the files in /tmp/special_tmp_files (no subdirectories), pre-loading all content'/tmp':mock.load('/tmp/special_tmp_files',{recursive:false,lazy:false}),'fakefile.txt':'content here'});

Whenconfig property values are astring orBuffer, a file is created with the provided content. For example, the following configuration creates a single file with string content (in addition to the two default directories).

mock({'path/to/file.txt':'file content here'});

To create a file with additional properties (owner, permissions, atime, etc.), use themock.file() function described below.

Create a factory for new files. Supported properties:

• content -string|Buffer File contents.
• mode -number File mode (permission and sticky bits). Defaults to0666.
• uid -number The user id. Defaults toprocess.getuid().
• gid -number The group id. Defaults toprocess.getgid().
• atime -Date The last file access time. Defaults tonew Date(). Updated when file contents are accessed.
• ctime -Date The last file change time. Defaults tonew Date(). Updated when file owner or permissions change.
• mtime -Date The last file modification time. Defaults tonew Date(). Updated when file contents change.
• birthtime -Date The time of file creation. Defaults tonew Date().

To create a mock filesystem with a very old file namedfoo, you could do something like this:

mock({foo:mock.file({content:'file content here',ctime:newDate(1),mtime:newDate(1)})});

Note that if you want to create a file with the default properties, you can provide astring orBuffer directly instead of callingmock.file().

Whenconfig property values are anObject, a directory is created. The structure of the object is the same as theconfig object itself. So an empty directory can be created with a simple object literal ({}). The following configuration creates a directory containing two files (in addition to the two default directories):

// note that this could also be written as// mock({'path/to/dir': { /** config */ }})mock({path:{to:{dir:{file1:'text content',file2:Buffer.from([1,2,3,4])}}}});

To create a directory with additional properties (owner, permissions, atime, etc.), use themock.directory() function described below.

Create a factory for new directories. Supported properties:

• mode -number Directory mode (permission and sticky bits). Defaults to0777.
• uid -number The user id. Defaults toprocess.getuid().
• gid -number The group id. Defaults toprocess.getgid().
• atime -Date The last directory access time. Defaults tonew Date().
• ctime -Date The last directory change time. Defaults tonew Date(). Updated when owner or permissions change.
• mtime -Date The last directory modification time. Defaults tonew Date(). Updated when an item is added, removed, or renamed.
• birthtime -Date The time of directory creation. Defaults tonew Date().
• items -Object Directory contents. Members will generate additional files, directories, or symlinks.

To create a mock filesystem with a directory with the relative pathsome/dir that has a mode of0755 and two child files, you could do something like this:

mock({'some/dir':mock.directory({mode:0755,items:{file1:'file one content',file2:Buffer.from([8,6,7,5,3,0,9])}})});

Note that if you want to create a directory with the default properties, you can provide anObject directly instead of callingmock.directory().

Using astring or aBuffer is a shortcut for creating files with default properties. Using anObject is a shortcut for creating a directory with default properties. There is no shortcut for creating symlinks. To create a symlink, you need to call themock.symlink() function described below.

Create a factory for new symlinks. Supported properties:

• path -string Path to the source (required).
• mode -number Symlink mode (permission and sticky bits). Defaults to0666.
• uid -number The user id. Defaults toprocess.getuid().
• gid -number The group id. Defaults toprocess.getgid().
• atime -Date The last symlink access time. Defaults tonew Date().
• ctime -Date The last symlink change time. Defaults tonew Date().
• mtime -Date The last symlink modification time. Defaults tonew Date().
• birthtime -Date The time of symlink creation. Defaults tonew Date().

To create a mock filesystem with a file and a symlink, you could do something like this:

mock({'some/dir':{'regular-file':'file contents','a-symlink':mock.symlink({path:'regular-file'})}});

Restore thefs binding to the real file system. This undoes the effect of callingmock(). Typically, you would set up a mock file system before running a test and restore the original after. Using a test runner withbeforeEach andafterEach hooks, this might look like the following:

beforeEach(function(){mock({'fake-file':'file contents'});});afterEach(mock.restore);

Execute calls to the real filesystem with mock.bypass()

// This file exists only on the real FS, not on the mocked FSconstrealFilePath='/path/to/real/file.txt';constmyData=mock.bypass(()=>fs.readFileSync(realFilePath,'utf-8'));

If you pass an asynchronous function or a promise-returning function tobypass(), a promise will be returned.

Asynchronous calls are supported, however, they are not recommended as they could produce unintended consequences ifanything else tries to access the mocked filesystem before they've completed.

asyncfunctiongetFileInfo(fileName){returnawaitmock.bypass(async()=>{conststats=awaitfs.promises.stat(fileName);constdata=awaitfs.promises.readFile(fileName);return{stats, data};});}

Usingnpm:

npm install mock-fs --save-dev

When you requiremock-fs, Node's ownfs module is patched to allow the binding to the underlying file system to be swapped out. If you requiremock-fsbefore any other modules that modifyfs (e.g.graceful-fs), the mock should behave as expected.

Notemock-fs is not compatible withgraceful-fs@3.x but works withgraceful-fs@4.x.

Mock file access is controlled based on file mode whereprocess.getuid() andprocess.getgid() are available (POSIX systems). On other systems (e.g. Windows) the file mode has no effect.

Tested on Linux, OSX, and Windows using Node 18 through 22. Check the tickets for a list ofknown issues.

.toMatchSnapshot inJest usesfs to load existing snapshots.IfmockFs is active, Jest isn't able to load existing snapshots. In such case it accepts all snapshotswithout diffing the old ones, which breaks the concept of snapshot testing.

Callingmock.restore() inafterEach is too late and it's necessary to call it before snapshot matching:

constactual=testedFunction()mock.restore()expect(actual).toMatchSnapshot()

Note: it's safe to callmock.restore multiple times, so it can still be called inafterEach and then manuallyin test cases which use snapshot testing.