Add ability to unload files from require cache (redux)

lib/cli/run-helpers.js

@@ -249,9 +249,7 @@ exports.watchRun = (
   };
 
   const purge = () => {
-    watchFiles.forEach(file => {
-      delete require.cache[file];
-    });
+    watchFiles.forEach(mocha.unloadFile);
   };
 
   loadAndRun();

lib/mocha.js

@@ -301,7 +301,6 @@ Mocha.prototype.ui = function(name) {
 };
 
 /**
- * @summary
  * Loads `files` prior to execution.
  *
  * @description
@@ -310,6 +309,8 @@ Mocha.prototype.ui = function(name) {
  *
  * @private
  * @see {@link Mocha#addFile}
+ * @see {@link Mocha#run}
+ * @see {@link Mocha#unloadFiles}
  * @param {Function} [fn] - Callback invoked upon completion.
  */
 Mocha.prototype.loadFiles = function(fn) {
@@ -324,6 +325,38 @@ Mocha.prototype.loadFiles = function(fn) {
   fn && fn();
 };
 
+/**
+ * Removes a previously loaded file from Node's `require` cache.
+ *
+ * @private
+ * @see {@link Mocha#unloadFiles}
+ * @param {string} file - Pathname of file to be unloaded.
+ */
+Mocha.prototype.unloadFile = function(file) {
+  delete require.cache[require.resolve(file)];
+};
+
+/**
+ * Unloads `files` from Node's `require` cache.
+ *
+ * @description
+ * This allows files to be "freshly" reloaded, providing the ability
+ * to reuse a Mocha instance programmatically.
+ *
+ * <strong>Not needed for (or used by) CLI.</strong>
+ *
+ * @public
+ * @see {@link Mocha#unloadFile}
+ * @see {@link Mocha#loadFiles}
+ * @see {@link Mocha#run}
+ * @returns {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.unloadFiles = function() {
+  this.files.forEach(this.unloadFile, this);
+  return this;
+};
+
 /**
  * Sets `grep` filter after escaping RegExp special characters.
  *
@@ -741,8 +774,7 @@ Object.defineProperty(Mocha.prototype, 'version', {
  */
 
 /**
- * @summary
- * Runs tests and invokes `fn()` when complete.
+ * Runs root suite and invokes `fn()` when complete.
  *
  * @description
  * To run tests multiple times (or to run tests in files that are
@@ -751,6 +783,7 @@ Object.defineProperty(Mocha.prototype, 'version', {
  *
  * @public
  * @see {@link Mocha#loadFiles}
+ * @see {@link Mocha#unloadFiles}
  * @see {@link Runner#run}
  * @param {DoneCB} [fn] - Callback invoked when test execution completed.
  * @return {Runner} runner instance
@@ -787,7 +820,7 @@ Mocha.prototype.run = function(fn) {
   exports.reporters.Base.hideDiff = options.hideDiff;
 
   function done(failures) {
-    fn = fn || function fn() {};
+    fn = fn || utils.noop;
     if (reporter.done) {
       reporter.done(failures, fn);
     } else {

test/unit/mocha.spec.js

@@ -226,6 +226,58 @@ describe('Mocha', function() {
     });
   });
 
+  describe('.unloadFile()', function() {
+    before(function() {
+      if (process.browser) {
+        this.skip();
+      }
+    });
+
+    it('should unload a specific file from cache', function() {
+      var mocha = new Mocha(opts);
+      var resolvedFilePath;
+      var filePath = __filename;
+
+      mocha.addFile(filePath);
+      mocha.loadFiles();
+      resolvedFilePath = require.resolve(filePath);
+      expect(require.cache, 'to have key', resolvedFilePath);
+
+      mocha.unloadFile(filePath);
+      expect(require.cache, 'not to have key', resolvedFilePath);
+    });
+  });
+
+  describe('.unloadFiles()', function() {
+    var path;
+
+    before(function() {
+      if (process.browser) {
+        this.skip();
+      } else {
+        path = require('path');
+      }
+    });
+
+    it('should unload all test files from cache', function() {
+      var mocha = new Mocha(opts);
+      var resolvedTestFiles;
+      var testFiles = [
+        __filename,
+        path.join(__dirname, 'throw.spec.js'),
+        path.join(__dirname, 'context.spec.js')
+      ];
+
+      testFiles.forEach(mocha.addFile, mocha);
+      mocha.loadFiles();
+      resolvedTestFiles = testFiles.map(require.resolve);
+      expect(require.cache, 'to have keys', resolvedTestFiles);
+
+      mocha.unloadFiles();
+      expect(require.cache, 'not to have keys', resolvedTestFiles);
+    });
+  });
+
   describe('error handling', function() {
     it('should throw reporter error if an invalid reporter is given', function() {
       var updatedOpts = {reporter: 'invalidReporter', reporterOptions: {}};