From 802fb0593a9a4d094e2290582760c2b43529fbd1 Mon Sep 17 00:00:00 2001 From: Juerg B <44573692+juergba@users.noreply.github.com> Date: Tue, 3 Sep 2019 08:48:40 +0200 Subject: [PATCH] Deprecate "debug" and remove "--debug" / "--debug-brk" flags (#3890) --- bin/mocha | 51 +++------------- docs/index.md | 57 +++++++++--------- lib/cli/node-flags.js | 2 +- lib/cli/run.js | 2 +- test/integration/options/debug.spec.js | 80 -------------------------- test/node-unit/cli/node-flags.spec.js | 4 +- 6 files changed, 41 insertions(+), 155 deletions(-) delete mode 100644 test/integration/options/debug.spec.js diff --git a/bin/mocha b/bin/mocha index 865f5b1f07..4b0ab8ff86 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]; - }); - // historical if (nodeArgs.gc) { deprecate( diff --git a/docs/index.md b/docs/index.md index be1511ef9e..50b5536aeb 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 Mocha Commands - mocha debug [spec..] Run tests with Mocha [default] - mocha init create a client-side Mocha setup at + mocha inspect [spec..] Run tests with Mocha [default] + mocha init create a client-side Mocha setup at 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 () [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 , -t ` -> _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 ` - -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 , --watch-extensions ` > _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 ` -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 , --exclude ,` + +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.js index feffaa93e2..8d378e1bf2 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 not diff --git a/lib/cli/run.js b/lib/cli/run.js index b0a16e6bdf..9adb602ca3 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.js deleted file mode 100644 index 297aee91f6..0000000000 --- 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.js index 1347f256a9..9871088117 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'); }); });