# `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 with `fs`-like methods without overriding the built-in `fs` module.
- The object created by `fs.Stats` is no longer an instance of `fs.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 for `process.cwd()`. This is `true` by default.
- `createTmp` - `boolean` Create a directory for `os.tmpdir()`. This is `true` by default.

### 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 to `0666`.
- uid - `number` The user id. Defaults to `process.getuid()`.
- gid - `number` The group id. Defaults to `process.getgid()`.
- atime - `Date` The last file access time. Defaults to `new Date()`. Updated when file contents are accessed.
- ctime - `Date` The last file change time. Defaults to `new Date()`. Updated when file owner or permissions change.
- mtime - `Date` The last file modification time. Defaults to `new Date()`. Updated when file contents change.
- birthtime - `Date` The time of file creation. Defaults to `new 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 to `0777`.
- uid - `number` The user id. Defaults to `process.getuid()`.
- gid - `number` The group id. Defaults to `process.getgid()`.
- atime - `Date` The last directory access time. Defaults to `new Date()`.
- ctime - `Date` The last directory change time. Defaults to `new Date()`. Updated when owner or permissions change.
- mtime - `Date` The last directory modification time. Defaults to `new Date()`. Updated when an item is added, removed, or renamed.
- birthtime - `Date` The time of directory creation. Defaults to `new 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 to `0666`.
- uid - `number` The user id. Defaults to `process.getuid()`.
- gid - `number` The group id. Defaults to `process.getgid()`.
- atime - `Date` The last symlink access time. Defaults to `new Date()`.
- ctime - `Date` The last symlink change time. Defaults to `new Date()`.
- mtime - `Date` The last symlink modification time. Defaults to `new Date()`.
- birthtime - `Date` The time of symlink creation. Defaults to `new 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);

## 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 `graceful-fs@3.x` but works with `graceful-fs@4.x`.

Mock `fs.Stats` objects have the following properties: `dev`, `ino`, `nlink`, `mode`, `size`, `rdev`, `blksize`, `blocks`, `atime`, `ctime`, `mtime`, `birthtime`, `uid`, and `gid`. In addition, all of the `is*()` method are provided (e.g. `isDirectory()`, `isFile()`, et al.).

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 6 through 11. 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.