Deprecate "debug" and remove "--debug" / "--debug-brk" flags (#3890)

bin/mocha

@@ -10,7 +10,7 @@
  * @private
  */
 
-const {deprecate, warn} = require('../lib/utils');
+const {deprecate} = require('../lib/utils');
 const {loadOptions} = require('../lib/cli/options');
 const {
   unparseNodeFlags,
@@ -20,7 +20,6 @@ const {
 const unparse = require('yargs-unparser');
 const debug = require('debug')('mocha:cli:mocha');
 const {aliases} = require('../lib/cli/run-option-metadata');
-const nodeEnv = require('node-environment-flags');
 
 const mochaArgs = {};
 const nodeArgs = {};
@@ -63,51 +62,19 @@ Object.keys(opts).forEach(opt => {
 
 // Native debugger handling
 // see https://nodejs.org/api/debugger.html#debugger_debugger
-// look for 'debug' or 'inspect' that would launch this debugger,
+// look for 'inspect' or 'debug' that would launch this debugger,
 // remove it from Mocha's opts and prepend it to Node's opts.
-// also coerce depending on Node.js version.
 // A deprecation warning will be printed by node, if applicable.
 // (mochaArgs._ are "positional" arguments, not prefixed with - or --)
-if (/^(debug|inspect)$/.test(mochaArgs._[0])) {
-  const command = mochaArgs._.shift();
-  disableTimeouts(command);
-  // don't conflict with inspector
-  ['debug', 'inspect', 'debug-brk', 'inspect-brk']
-    .filter(opt => opt in nodeArgs || opt in mochaArgs)
-    .forEach(opt => {
-      warn(`command "${command}" provided; --${opt} ignored`);
-      delete nodeArgs[opt];
-      delete mochaArgs[opt];
-    });
-  nodeArgs._ = [
-    parseInt(
-      process.version
-        .slice(1)
-        .split('.')
-        .shift(),
-      10
-    ) >= 8
-      ? 'inspect'
-      : 'debug'
-  ];
+if (mochaArgs._) {
+  const i = mochaArgs._.findIndex(val => val === 'inspect' || val === 'debug');
+  if (i > -1) {
+    const [command] = mochaArgs._.splice(i, 1);
+    disableTimeouts('inspect');
+    nodeArgs._ = [command];
+  }
 }
 
-// allow --debug to invoke --inspect on Node.js v8 or newer.
-['debug', 'debug-brk']
-  .filter(opt => opt in nodeArgs && !nodeEnv.has(opt))
-  .forEach(opt => {
-    const newOpt = opt === 'debug' ? 'inspect' : 'inspect-brk';
-    warn(
-      `"--${opt}" is not available in Node.js ${
-        process.version
-      }; use "--${newOpt}" instead.`
-    );
-    nodeArgs[newOpt] = nodeArgs[opt];
-    mochaArgs.timeout = false;
-    debug(`--${opt} -> ${newOpt}`);
-    delete nodeArgs[opt];
-  });
-
 // historical
 if (nodeArgs.gc) {
   deprecate(

docs/index.md

@@ -39,7 +39,7 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js][] and in
 - [config file support](#-config-path)
 - [mocha.opts file support](#-opts-path)
 - clickable suite titles to filter test execution
-- [node debugger support](#-debug-inspect-debug-brk-inspect-brk-debug-inspect)
+- [node debugger support](#-inspect-inspect-brk-inspect)
 - [detects multiple calls to `done()`](#detects-multiple-calls-to-done)
 - [use any assertion library you want](#assertions)
 - [extensible reporting, bundled with 9+ reporters](#reporters)
@@ -828,8 +828,8 @@ mocha [spec..]
 Run tests with Mocha
 
 Commands
-  mocha debug [spec..]  Run tests with Mocha                           [default]
-  mocha init <path>     create a client-side Mocha setup at <path>
+  mocha inspect [spec..]  Run tests with Mocha                         [default]
+  mocha init <path>       create a client-side Mocha setup at <path>
 
 Rules & Behavior
   --allow-uncaught           Allow uncaught errors to propagate        [boolean]
@@ -844,9 +844,9 @@ Rules & Behavior
   --global, --globals        List of allowed global variables            [array]
   --retries                  Retry failed tests this many times         [number]
   --slow, -s                 Specify "slow" test threshold (in milliseconds)
-                                                          [number] [default: 75]
+                                                          [string] [default: 75]
   --timeout, -t, --timeouts  Specify test timeout threshold (in milliseconds)
-                                                        [number] [default: 2000]
+                                                        [string] [default: 2000]
   --ui, -u                   Specify user interface    [string] [default: "bdd"]
 
 Reporting & Output
@@ -863,17 +863,18 @@ Reporting & Output
   -O                                        (<k=v,[k1=v1,..]>)           [array]
 
 Configuration
-  --config   Path to config file                    [default: (nearest rc file)]
-  --opts     Path to `mocha.opts`        [string] [default: "./test/mocha.opts"]
+  --config   Path to config file           [string] [default: (nearest rc file)]
+  --opts     Path to `mocha.opts` (DEPRECATED)
+                                         [string] [default: "./test/mocha.opts"]
   --package  Path to package.json for config                            [string]
 
 File Handling
-  --ignore, --exclude              Ignore file(s) or glob pattern(s)
-                                                       [array] [default: (none)]
   --extension, --watch-extensions  File extension(s) to load and/or watch
                                                            [array] [default: js]
   --file                           Specify file(s) to be loaded prior to root
                                    suite execution     [array] [default: (none)]
+  --ignore, --exclude              Ignore file(s) or glob pattern(s)
+                                                       [array] [default: (none)]
   --recursive                      Look for tests in subdirectories    [boolean]
   --require, -r                    Require module      [array] [default: (none)]
   --sort, -S                       Sort test files                     [boolean]
@@ -890,10 +891,10 @@ Positional Arguments
                                                      [array] [default: ["test"]]
 
 Other Options
-  --help, -h     Show usage information & exit                         [boolean]
-  --version, -V  Show version number & exit                            [boolean]
-  --list-interfaces   List built-in user interfaces & exit                  [boolean]
-  --list-reporters    List built-in reporters & exit                        [boolean]
+  --help, -h         Show usage information & exit                     [boolean]
+  --version, -V      Show version number & exit                        [boolean]
+  --list-interfaces  List built-in user interfaces & exit              [boolean]
+  --list-reporters   List built-in reporters & exit                    [boolean]
 
 Mocha Resources
     Chat: https://gitter.im/mochajs/mocha
@@ -987,7 +988,7 @@ Note: A test that executes for _half_ of the "slow" time will be highlighted _in
 
 ### `--timeout <ms>, -t <ms>`
 
-> _Update in v6.0.0: `--no-timeout` is implied when invoking Mocha using debug flags. It is equivalent to `--timeout 0`. `--timeout 99999999` is no longer needed._
+> _Update in v6.0.0: `--no-timeout` is implied when invoking Mocha using inspect flags. It is equivalent to `--timeout 0`. `--timeout 99999999` is no longer needed._
 
 Specifies the test case timeout, defaulting to two (2) seconds (2000 milliseconds). Tests taking longer than this amount of time will be marked as failed.
 
@@ -1079,14 +1080,6 @@ Specify an explicit path to a [`package.json` file](#configuring-mocha-nodejs) (
 
 By default, Mocha looks for a `package.json` in the current working directory or nearest ancestor, and will use the first file found (regardless of whether it contains a `mocha` property); to suppress `package.json` lookup, use `--no-package`.
 
-### `--ignore <file|directory|glob>`
-
-Explicitly ignore (exclude) one or more test files, directories or globs (e.g., `some/**/files*`) that would otherwise be loaded.
-
-Files specified using `--file` _are not affected_ by this option.
-
-Can be specified multiple times.
-
 ### `--extension <ext>, --watch-extensions <ext>`
 
 > _Updated in v6.0.0. Previously `--watch-extensions`, but now expanded to affect general test file loading behavior. `--watch-extensions` is now an alias_
@@ -1099,14 +1092,22 @@ Specifying `--extension` will _remove_ `.js` as a test file extension; use `--ex
 
 ### `--file <file|directory|glob>`
 
-Explicitly _include_ a test file to be loaded before other test files files. Multiple uses of `--file` are allowed, and will be loaded in order given.
+Explicitly _include_ a test file to be loaded before other test files. Multiple uses of `--file` are allowed, and will be loaded in order given.
 
 Useful if you want to declare, for example, hooks to be run before every test across all other test files.
 
 Files specified this way are not affected by `--sort` or `--recursive`.
 
 Files specified in this way should contain one or more suites, tests or hooks. If this is not the case, consider `--require` instead.
 
+### `--ignore <file|directory|glob>, --exclude <file|directory|glob>,`
+
+Explicitly ignore (exclude) one or more test files, directories or globs (e.g., `some/**/files*`) that would otherwise be loaded.
+
+Files specified using `--file` _are not affected_ by this option.
+
+Can be specified multiple times.
+
 ### `--recursive`
 
 When looking for test files, recurse into subdirectories.
@@ -1178,15 +1179,15 @@ Use the _inverse_ of the match specified by `--grep` or `fgrep`.
 
 Requires either `--grep` or `--fgrep` (but not both).
 
-### `--debug, --inspect, --debug-brk, --inspect-brk, debug, inspect`
+### `--inspect, --inspect-brk, inspect`
 
-> _BREAKING CHANGE in v6.0.0; `-d` is no longer an alias for `--debug`. Other updates in v6.0.0: In versions of Node.js implementing `--inspect` and `--inspect-brk`, `--debug` and `--debug-brk` are respectively aliases for these two options. Likewise, `debug` (not `--debug`) is an alias for `inspect` (not `--inspect`) in Node.js versions where `debug` is deprecated._
+> _BREAKING CHANGE in v7.0.0; `--debug` / `--debug-brk` are removed and `debug` is deprecated._
 
-Enables Node.js' debugger or inspector.
+Enables Node.js' inspector.
 
-Use `--inspect` / `--inspect-brk` / `--debug` / `--debug-brk` to launch the V8 inspector for use with Chrome Dev Tools.
+Use `--inspect` / `--inspect-brk` to launch the V8 inspector for use with Chrome Dev Tools.
 
-Use `inspect` / `debug` to launch Node.js' internal debugger.
+Use `inspect` to launch Node.js' internal debugger.
 
 All of these options are mutually exclusive.
 

lib/cli/node-flags.js

@@ -14,7 +14,7 @@ const unparse = require('yargs-unparser');
  * @see {@link impliesNoTimeouts}
  * @private
  */
-const debugFlags = new Set(['debug', 'debug-brk', 'inspect', 'inspect-brk']);
+const debugFlags = new Set(['inspect', 'inspect-brk']);
 
 /**
  * Mocha has historical support for various `node` and V8 flags which might not

lib/cli/run.js

@@ -38,7 +38,7 @@ const GROUPS = {
   CONFIG: 'Configuration'
 };
 
-exports.command = ['$0 [spec..]', 'debug [spec..]'];
+exports.command = ['$0 [spec..]', 'inspect'];
 
 exports.describe = 'Run tests with Mocha';
 

test/node-unit/cli/node-flags.spec.js

@@ -86,10 +86,8 @@ describe('node-flags', function() {
   });
 
   describe('impliesNoTimeouts()', function() {
-    it('should return true for debug/inspect flags', function() {
-      expect(impliesNoTimeouts('debug'), 'to be true');
+    it('should return true for inspect flags', function() {
       expect(impliesNoTimeouts('inspect'), 'to be true');
-      expect(impliesNoTimeouts('debug-brk'), 'to be true');
       expect(impliesNoTimeouts('inspect-brk'), 'to be true');
     });
   });