Helper to bypass mock FS & expose real files/directories

lib/filesystem.js

@@ -112,6 +112,8 @@ FileSystem.prototype.getItem = function(filepath) {
     if (item) {
       if (item instanceof Directory && name !== currentParts[i]) {
         // make sure traversal is allowed
+        // This fails for Windows directories which do not have execute permission, by default. It may be a good idea
+        // to change this logic to windows-friendly. See notes in mock.createDirectoryInfoFromPaths()
         if (!item.canExecute()) {
           throw new FSError('EACCES', filepath);
         }

lib/index.js

@@ -17,6 +17,15 @@ const realCreateWriteStream = fs.createWriteStream;
 const realStats = realBinding.Stats;
 const realStatWatcher = realBinding.StatWatcher;
 
+// File Permissions
+const S_IRUSR = 0o400;
+const S_IRGRP = 0o40;
+const S_IROTH = 0o4;
+
+const S_IXUSR = 0o100;
+const S_IXGRP = 0o10;
+const S_IXOTH = 0o1;
+
 /**
  * Pre-patch fs binding.
  * This allows mock-fs to work properly under nodejs v10+ readFile
@@ -183,3 +192,117 @@ exports.directory = FileSystem.directory;
  * Create a symbolic link factory.
  */
 exports.symlink = FileSystem.symlink;
+
+/**
+ * Perform action, bypassing mock FS
+ * @example
+ * // This file exists on the real FS, not on the mocked FS
+ * const filePath = '/path/file.json';
+ * const data = mock.bypass(() => fs.readFileSync(filePath, 'utf-8'));
+ */
+exports.bypass = function(fn) {
+  if (typeof fn !== 'function') {
+    throw new Error(`Must provide a function to perform for mock.bypass()`);
+  }
+
+  // Deactivate mocked bindings
+  const binding = process.binding('fs')._mockedBinding;
+  delete process.binding('fs')._mockedBinding;
+
+  // Perform action
+  const res = fn();
+
+  // Reactivate mocked bindings
+  process.binding('fs')._mockedBinding = binding;
+
+  return res;
+};
+
+/**
+ * Populate a DirectoryItems object to use with mock() from a series of paths to files/directories
+ */
+exports.createDirectoryInfoFromPaths = function(paths, options) {
+  return exports.bypass(() => {
+    const res = {};
+
+    /* Get options or apply defaults */
+    let recursive = options && options.recursive;
+    let lazyLoad = options && options.lazyLoad;
+    if (recursive === undefined) {
+      recursive = true;
+    }
+    if (lazyLoad === undefined) {
+      lazyLoad = true;
+    }
+
+    if (Array.isArray(paths)) {
+      paths.forEach(p => scan(p, true));
+    } else {
+      scan(paths, true);
+    }
+
+    return res;
+
+    function scan(p, isRoot) {
+      if (typeof p !== 'string') {
+        throw new Error(
+          `Must provide path or array of paths (as strings) to createDirectoryInfoFromPaths()`
+        );
+      }
+
+      p = path.normalize(p);
+
+      const stats = fs.statSync(p);
+      if (stats.isFile()) {
+        addFile(p, stats);
+      } else if ((isRoot || recursive) && stats.isDirectory()) {
+        const dirStats = Object.assign({}, stats);
+        // On windows platforms, directories do not have the executable flag, which causes FileSystem.prototype.getItem
+        // to think that the directory cannot be traversed. This is a workaround, however, a better solution may be to
+        // re-think the logic in FileSystem.prototype.getItem
+        // This workaround adds executable privileges if read privileges are found
+        if (process.platform === 'win32') {
+          // prettier-ignore
+          dirStats.mode |=
+            ((dirStats.mode & S_IRUSR) && S_IXUSR) |
+            ((dirStats.mode & S_IRGRP) && S_IXGRP) |
+            ((dirStats.mode & S_IROTH) && S_IXOTH);
+        }
+        res[p] = exports.directory(dirStats);
+        fs.readdirSync(p).forEach(subPath => scan(path.join(p, subPath)));
+      }
+    }
+
+    function addFile(p, stats) {
+      res[p] = () => {
+        const content = lazyLoad
+          ? exports.bypass(() => fs.readFileSync(p))
+          : '';
+
+        const file = exports.file(Object.assign({}, stats, {content}))();
+
+        if (lazyLoad) {
+          Object.defineProperty(file, '_content', {
+            get() {
+              const res = exports.bypass(() => fs.readFileSync(p));
+              Object.defineProperty(file, '_content', {
+                value: res,
+                writable: true
+              });
+              return res;
+            },
+            set(data) {
+              Object.defineProperty(file, '_content', {
+                value: data,
+                writable: true
+              });
+            },
+            configurable: true
+          });
+        }
+
+        return file;
+      };
+    }
+  });
+};

lib/item.js

@@ -140,8 +140,8 @@ Item.prototype.canExecute = function() {
   let can = false;
   if (uid === 0) {
     can = true;
-  } else if (uid === this._uid || uid !== uid) {
-    // (uid !== uid) means uid is NaN, only for windows
+  } else if (uid === this._uid || isNaN(uid)) {
+    // NaN occurs on windows
     can = (permissions.USER_EXEC & this._mode) === permissions.USER_EXEC;
   } else if (gid === this._gid) {
     can = (permissions.GROUP_EXEC & this._mode) === permissions.GROUP_EXEC;

readme.md

@@ -1,3 +1,5 @@
+[![Build Status](https://github.com/tschaub/mock-fs/workflows/Test/badge.svg)](https://github.com/tschaub/mock-fs/actions?workflow=Test)
+
 # `mock-fs`
 
 The `mock-fs` module allows Node's built-in [`fs` module](http://nodejs.org/api/fs.html) 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.
@@ -58,7 +60,51 @@ 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
+### Automatically Creating Files & Directories
+
+You can create files and directories automatically by providing paths to `mock.createDirectoryInfoFromPaths()`. This will
+read the filesystem for the paths you provide and automatically create files and directories for them.
+
+### <a id='cdifp'>`mock.createDirectoryInfoFromPaths(paths, options)`</a>
+
+#### <a id='cdifp_paths'>`paths`</a> - `string` or `string[]`
+
+#### <a id='cdifp_options'>`options`</a>
+
+The second (optional) argument may include the properties below.
+
+ * `lazyLoad` - `boolean` File content does not get loaded until explicitly read. This is `true` by default.
+ * `recursive` - `boolean` Load all files and directories recursively.  This is `true` by default.
+
+#### Examples
+
+Given the following directory structure
+```
+- /root/
+  - subdir/
+     - file2.txt
+  - file1.txt
+- /lib/
+  - library.js
+  - extra.js
+```
+```js
+// Creates files and dirs for all in `/root` and creates the directory `/lib` and the file `/lib/extra.js`
+// Notes: 
+//        - /lib/library.js is not included
+//        - Files are lazy-loaded
+mock(mock.createDirectoryInfoFromPaths([ '/root', '/lib/extra.js' ]));
+
+// -------------------------------------------------------------------------------------
+
+// Creates `/root` directory and `/root/file1.txt`
+// Notes: 
+//        - subdir and its contents are not loaded (due to recursive=false)
+//        - Files content is loaded into memory immediately (due to lazyLoad=false)
+mock(mock.createDirectoryInfoFromPaths([ '/root' ], { recursive: false, lazyLoad: false }));
+```
+
+### Manually 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).
 ```js
@@ -95,7 +141,7 @@ mock({
 
 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
+### Manually 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):
 ```js
@@ -187,6 +233,18 @@ beforeEach(function() {
 afterEach(mock.restore);
 ```
 
+### Bypassing the mock file system
+
+Sometimes you will want to execute calls against the actual file-system. In order to do that, we've provided a helper.
+
+### <a id='mockrestore'>`mock.bypass(fn)`</a>
+
+```js
+// 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'));
+```
+
 ## Install
 
 Using `npm`:
@@ -222,6 +280,4 @@ 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.
-
-[![Build Status](https://github.com/tschaub/mock-fs/workflows/Test/badge.svg)](https://github.com/tschaub/mock-fs/actions?workflow=Test)
+in test cases which use snapshot testing.

test/assets/dir/file2.txt

@@ -0,0 +1 @@
+data2

test/assets/dir/subdir/file3.txt

@@ -0,0 +1 @@
+data3

test/assets/file1.txt

@@ -0,0 +1 @@
+data1