☕️ Classic, reliable, trusted test framework for Node.js and the browser
Deprecate "debug" and remove "--debug" / "--debug-brk" flags (#3890)
Juerg B802fb0593a9a
diff --git a/bin/mocha b/bin/mochaindex 865f5b1f..4b0ab8ff 100755--- a/bin/mocha+++ b/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];- });-// historicalif (nodeArgs.gc) {deprecate(diff --git a/docs/index.md b/docs/index.mdindex be1511ef..50b5536a 100644--- a/docs/index.md+++ b/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 MochaCommands- 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 rootsuite 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 ResourcesChat: 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,7 +1092,7 @@ 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.@@ -1107,6 +1100,14 @@ 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.diff --git a/lib/cli/node-flags.js b/lib/cli/node-flags.jsindex feffaa93..8d378e1b 100644--- a/lib/cli/node-flags.js+++ b/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 notdiff --git a/lib/cli/run.js b/lib/cli/run.jsindex b0a16e6b..9adb602c 100644--- a/lib/cli/run.js+++ b/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';diff --git a/test/integration/options/debug.spec.js b/test/integration/options/debug.spec.jsdeleted file mode 100644index 297aee91..00000000--- a/test/integration/options/debug.spec.js+++ /dev/null@@ -1,80 +0,0 @@-'use strict';--var helpers = require('../helpers');-var invokeMocha = helpers.invokeMocha;-var DEFAULT_FIXTURE = helpers.DEFAULT_FIXTURE;--describe('--debug', function() {- describe('Node.js v8+', function() {- before(function() {- if (process.version.substring(0, 2) === 'v6') {- this.skip();- }- });-- it('should invoke --inspect', function(done) {- invokeMocha(- ['--debug', DEFAULT_FIXTURE],- function(err, res) {- if (err) {- return done(err);- }- expect(res, 'to contain output', /Debugger listening/i);- done();- },- 'pipe'- );- });-- it('should invoke --inspect-brk', function(done) {- var proc = invokeMocha(- ['--debug-brk', DEFAULT_FIXTURE],- function(err, res) {- if (err) {- return done(err);- }- expect(res, 'to contain output', /Debugger listening/i);- done();- },- 'pipe'- );-- // debugger must be manually killed- setTimeout(function() {- process.kill(proc.pid, 'SIGINT');- }, 2000);- });-- it('should respect custom host/port', function(done) {- invokeMocha(- ['--debug=127.0.0.1:9229', DEFAULT_FIXTURE],- function(err, res) {- if (err) {- return done(err);- }- expect(- res,- 'to contain output',- /Debugger listening on .*127.0.0.1:9229/i- );- done();- },- 'pipe'- );- });-- it('should warn about incorrect usage for version', function(done) {- invokeMocha(- ['--debug=127.0.0.1:9229', DEFAULT_FIXTURE],- function(err, res) {- if (err) {- return done(err);- }- expect(res, 'to contain output', /"--debug" is not available/i);- done();- },- 'pipe'- );- });- });-});diff --git a/test/node-unit/cli/node-flags.spec.js b/test/node-unit/cli/node-flags.spec.jsindex 1347f256..98710881 100644--- a/test/node-unit/cli/node-flags.spec.js+++ b/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');});});