@luminati-io/mock-fs
v5.2.0-lum.1
Published
A configurable mock file system (with node 20.11.0 support). You know, for testing.
Downloads
117
Readme
mock-fs
The mock-fs
module allows Node's built-in fs
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.
Example
The code below makes it so the fs
module is temporarily backed by a mock file system with a few files and directories.
const mock = 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 the fs
module (so that it is backed by your real file system), call mock.restore()
. Note that calling this may be mandatory in some cases. See istanbuljs/nyc#324
// after a test runs
mock.restore();
Upgrading to version 4
Instead of overriding all methods of the built-in fs
module, the library now overrides process.binding('fs')
. The purpose of this change is to avoid conflicts with other libraries that override fs
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's fs
module.
Breaking changes:
- The
mock.fs()
function has been removed. This returned an object withfs
-like methods without overriding the built-infs
module. - The object created by
fs.Stats
is no longer an instance offs.Stats
(though it has all the same properties and methods). - Lazy
require()
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.
Docs
mock(config, options)
Configure the fs
module so it is backed by an in-memory file system.
Calling mock
sets up a mock file system with two directories by default: process.cwd()
and os.tmpdir()
(or os.tmpDir()
for older Node). When called with no arguments, just these two directories are created. When called with a config
object, additional files, directories, and symlinks are created. To avoid creating a directory for process.cwd()
and os.tmpdir()
, see the options
below.
Property names of the config
object are interpreted as relative paths to resources (relative from process.cwd()
). Property values of the config
object are interpreted as content or configuration for the generated resources.
Note that paths should always use forward slashes (/
) - even on Windows.
options
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.
Loading real files & directories
You can load real files and directories into the mock system using mock.load()
Notes
- All stat information is duplicated (dates, permissions, etc)
- By default, all files are lazy-loaded, unless you specify the
{lazy: false}
option
options
| Option | Type | Default | Description | | --------- | ------- | ------- | ------------ | lazy | boolean | true | File content isn't loaded until explicitly read | recursive | boolean | true | Load all files and directories recursively
mock.load(path, options)
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'
});
Creating files
When config
property values are a string
or Buffer
, 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 the mock.file()
function described below.
mock.file(properties)
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 named foo
, you could do something like this:
mock({
foo: mock.file({
content: 'file content here',
ctime: new Date(1),
mtime: new Date(1)
})
});
Note that if you want to create a file with the default properties, you can provide a string
or Buffer
directly instead of calling mock.file()
.
Creating directories
When config
property values are an Object
, a directory is created. The structure of the object is the same as the config
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 the mock.directory()
function described below.
mock.directory(properties)
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 path some/dir
that has a mode of 0755
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 an Object
directly instead of calling mock.directory()
.
Creating symlinks
Using a string
or a Buffer
is a shortcut for creating files with default properties. Using an Object
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 the mock.symlink()
function described below.
mock.symlink(properties)
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'
})
}
});
Restoring the file system
mock.restore()
Restore the fs
binding to the real file system. This undoes the effect of calling mock()
. Typically, you would set up a mock file system before running a test and restore the original after. Using a test runner with beforeEach
and afterEach
hooks, this might look like the following:
beforeEach(function() {
mock({
'fake-file': 'file contents'
});
});
afterEach(mock.restore);
Bypassing the mock file system
mock.bypass(fn)
Execute calls to the real filesystem with mock.bypass()
// This file exists only on the real FS, not on the mocked FS
const realFilePath = '/path/to/real/file.txt';
const myData = mock.bypass(() => fs.readFileSync(realFilePath, 'utf-8'));
If you pass an asynchronous function or a promise-returning function to bypass()
, a promise will be returned.
Async Warning
Asynchronous calls are supported, however, they are not recommended as they could produce unintended consequences if anything else tries to access the mocked filesystem before they've completed.
async function getFileInfo(fileName) {
return await mock.bypass(async () => {
const stats = await fs.promises.stat(fileName);
const data = await fs.promises.readFile(fileName);
return {stats, data};
});
}
Install
Using npm
:
npm install mock-fs --save-dev
Caveats
When you require mock-fs
, Node's own fs
module is patched to allow the binding to the underlying file system to be swapped out. If you require mock-fs
before any other modules that modify fs
(e.g. graceful-fs
), the mock should behave as expected.
Note mock-fs
is not compatible with [email protected]
but works with [email protected]
.
Mock file access is controlled based on file mode where process.getuid()
and process.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 12 through 16. Check the tickets for a list of known issues.
Using with Jest Snapshot Testing
.toMatchSnapshot
in Jest uses fs
to load existing snapshots.
If mockFs
is active, Jest isn't able to load existing snapshots. In such case it accepts all snapshots
without diffing the old ones, which breaks the concept of snapshot testing.
Calling mock.restore()
in afterEach
is too late and it's necessary to call it before snapshot matching:
const actual = testedFunction()
mock.restore()
expect(actual).toMatchSnapshot()
Note: it's safe to call mock.restore
multiple times, so it can still be called in afterEach
and then manually
in test cases which use snapshot testing.