Add ability to pass in test files to be ran before positional files v…

…ia --file

Fixes #3181

bin/_mocha

@@ -120,6 +120,12 @@ const play = (arr, interval) => {
 
 let files = [];
 
+/**
+ * File args.
+ */
+
+let fileArgs = [];
+
 /**
  * Globals.
  */
@@ -199,7 +205,8 @@ program
   .option('--delay', 'wait for async suite definition')
   .option('--allow-uncaught', 'enable uncaught errors to propagate')
   .option('--forbid-only', 'causes test marked with only to fail the suite')
-  .option('--forbid-pending', 'causes pending tests and test marked with skip to fail the suite');
+  .option('--forbid-pending', 'causes pending tests and test marked with skip to fail the suite')
+  .option('--file <file>', 'include a file to be ran during the suite', list, []);
 
 program._name = 'mocha';
 
@@ -271,6 +278,12 @@ program.on('option:require', mod => {
   requires.push(mod);
 });
 
+// --file
+
+program.on('option:file', mod => {
+  fileArgs.push(mod);
+});
+
 // If not already done, load mocha.opts
 if (!process.env.LOADED_MOCHA_OPTS) {
   getOptions();
@@ -497,13 +510,16 @@ if (!files.length) {
 }
 
 // resolve
-
+fileArgs = fileArgs.map(path => resolve(path));
 files = files.map(path => resolve(path));
 
 if (program.sort) {
   files.sort();
 }
 
+// add files given through --file to be ran first
+files = fileArgs.concat(files);
+
 // --watch
 
 let runner;

docs/index.md

@@ -25,17 +25,17 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js](https://n
 - [maps uncaught exceptions to the correct test case](#browser-specific-methods)
 - [async test timeout support](#delayed-root-suite)
 - [test retry support](#retry-tests)
-- [test-specific timeouts](#test-level) 
+- [test-specific timeouts](#test-level)
 - [growl notification support](#mochaopts)
 - [reports test durations](#test-duration)
 - [highlights slow tests](#dot-matrix)
-- [file watcher support](#min) 
-- [global variable leak detection](#--check-leaks) 
-- [optionally run tests that match a regexp](#-g---grep-pattern) 
+- [file watcher support](#min)
+- [global variable leak detection](#--check-leaks)
+- [optionally run tests that match a regexp](#-g---grep-pattern)
 - [auto-exit to prevent "hanging" with an active loop](#--exit----no-exit)
 - [easily meta-generate suites](#markdown) & [test-cases](#list)
 - [mocha.opts file support](#mochaopts)
-- clickable suite titles to filter test execution  
+- clickable suite titles to filter test execution
 - [node debugger support](#-d---debug)
 - detects multiple calls to `done()`
 - [use any assertion library you want](#assertions)
@@ -297,7 +297,7 @@ describe('hooks', function() {
 });
 ```
 
-> Tests can appear before, after, or interspersed with your hooks.  Hooks will run in the order they are defined, as appropriate; all `before()` hooks run (once), then any `beforeEach()` hooks, tests, any `afterEach()` hooks, and finally `after()` hooks (once).  
+> Tests can appear before, after, or interspersed with your hooks.  Hooks will run in the order they are defined, as appropriate; all `before()` hooks run (once), then any `beforeEach()` hooks, tests, any `afterEach()` hooks, and finally `after()` hooks (once).
 
 ### Describing Hooks
 
@@ -529,9 +529,9 @@ it('should only test in the correct environment', function() {
 });
 ```
 
-The above test will be reported as [pending](#pending-tests).  It's also important to note that calling `this.skip()` will effectively *abort* the test.  
+The above test will be reported as [pending](#pending-tests).  It's also important to note that calling `this.skip()` will effectively *abort* the test.
 
-> *Best practice*: To avoid confusion, do not execute further instructions in a test or hook after calling `this.skip()`.  
+> *Best practice*: To avoid confusion, do not execute further instructions in a test or hook after calling `this.skip()`.
 
 Contrast the above test with the following code:
 
@@ -737,6 +737,7 @@ Mocha supports the `err.expected` and `err.actual` properties of any thrown `Ass
     --debug-brk                             enable node's debugger breaking on the first line
     --globals <names>                       allow the given comma-delimited global [names]
     --es_staging                            enable all staged features
+    --file <file>                           include a file to be ran during the suite [file]
     --harmony<_classes,_generators,...>     all node --harmony* flags are available
     --preserve-symlinks                     Instructs the module loader to preserve symbolic links when resolving and caching modules
     --icu-data-dir                          include ICU data

test/integration/fixtures/options/file-alpha.fixture.js

@@ -0,0 +1,9 @@
+'use strict';
+
+describe('alpha', function () {
+  it('should be executed first', function () {
+    if (global.beta) {
+      throw new Error('alpha was not executed first');
+    }
+  });
+});

test/integration/fixtures/options/file-beta.fixture.js

@@ -0,0 +1,7 @@
+'use strict';
+
+describe('beta', function () {
+  it('should be executed second', function () {
+    global.beta = 1;
+  });
+});

test/integration/helpers.js

@@ -129,7 +129,12 @@ module.exports = {
    * @param {Function} done - Callback
    * @param {string} cwd - Current working directory for mocha run, optional
    */
-  invokeMocha: invokeMocha
+  invokeMocha: invokeMocha,
+
+  /**
+   * Resolves the path to a fixture to the full path.
+   */
+  resolveFixturePath: resolveFixturePath
 };
 
 function invokeMocha (args, fn, cwd) {

test/integration/options.spec.js

@@ -4,6 +4,7 @@ var path = require('path');
 var assert = require('assert');
 var run = require('./helpers').runMochaJSON;
 var directInvoke = require('./helpers').invokeMocha;
+var resolvePath = require('./helpers').resolveFixturePath;
 var args = [];
 
 describe('options', function () {
@@ -91,6 +92,29 @@ describe('options', function () {
     });
   });
 
+  describe.only('--file', function () {
+    before(function () {
+      args = ['--file', resolvePath('options/file-alpha.fixture.js')];
+    });
+
+    it('should run tests passed via file first', function (done) {
+      run('options/file-beta.fixture.js', args, function (err, res) {
+        if (err) {
+          done(err);
+          return;
+        }
+        assert.equal(res.stats.pending, 0);
+        assert.equal(res.stats.passes, 2);
+        assert.equal(res.stats.failures, 0);
+
+        assert.equal(res.passes[0].fullTitle,
+          'alpha should be executed first');
+        assert.equal(res.code, 0);
+        done();
+      });
+    });
+  });
+
   describe('--delay', function () {
     before(function () {
       args = ['--delay'];