Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ 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/mocha
index 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];
- });
-
// historical
if (nodeArgs.gc) {
deprecate(
diff --git a/docs/index.md b/docs/index.md
index 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 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,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.js
index 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 not
diff --git a/lib/cli/run.js b/lib/cli/run.js
index 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.js
deleted file mode 100644
index 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.js
index 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');
});
});