Soft deprecate configuration via "mocha.opts" (#3968)

docs/index.md

@@ -1065,7 +1065,7 @@ By default, Mocha will search for a config file if `--config` is not specified;
 
 ### `--opts <path>`
 
-> _Updated in v6.0.0; added `--no-opts`._
+> _Deprecated._
 
 Specify a path to [`mocha.opts`](#mochaopts).
 
@@ -1636,14 +1636,14 @@ tests as shown below:
 
 > _New in v6.0.0_
 
-In addition to supporting the legacy [`mocha.opts`](#mochaopts) run-control format, Mocha now supports configuration files, typical of modern command-line tools, in several formats:
+In addition to supporting the deprecated [`mocha.opts`](#mochaopts) run-control format, Mocha now supports configuration files, typical of modern command-line tools, in several formats:
 
 - **JavaScript**: Create a `.mocharc.js` in your project's root directory, and export an object (`module.exports = {/* ... */}`) containing your configuration.
 - **YAML**: Create a `.mocharc.yaml` (or `.mocharc.yml`) in your project's root directory.
 - **JSON**: Create a `.mocharc.json` (or `.mocharc.jsonc`) in your project's root directory. Comments &mdash; while not valid JSON &mdash; are allowed in this file, and will be ignored by Mocha.
 - **package.json**: Create a `mocha` property in your project's `package.json`.
 
-Mocha suggests using one of the above strategies for configuration instead of the legacy `mocha.opts` format.
+Mocha suggests using one of the above strategies for configuration instead of the deprecated `mocha.opts` format.
 
 ### Custom Locations
 
@@ -1693,7 +1693,7 @@ Configurations can inherit from other modules using the `extends` keyword. See [
 
 ## `mocha.opts`
 
-> _Updated in v6.0.0; `mocha.opts` is now considered "legacy" &mdash; though not yet deprecated &mdash; and we recommend using a configuration file instead._
+> _`mocha.opts` file support is DEPRECATED and will be removed from a future version of Mocha. We recommend using a configuration file instead._
 
 Mocha will attempt to load `"./test/mocha.opts"` as a run-control file of sorts.
 

example/config/.mocharc.js

@@ -7,7 +7,7 @@
 module.exports = {
   diff: true,
   extension: ['js'],
-  opts: './test/mocha.opts',
+  opts: false,
   package: './package.json',
   reporter: 'spec',
   slow: 75,

example/config/.mocharc.json

@@ -5,7 +5,7 @@
 {
   "diff": true,
   "extension": ["js"],
-  "opts": "./test/mocha.opts",
+  "opts": false,
   "package": "./package.json",
   "reporter": "spec",
   "slow": 75,

example/config/.mocharc.jsonc

@@ -5,7 +5,7 @@
 {
   "diff": true,
   "extension": ["js"],
-  "opts": "./test/mocha.opts",
+  "opts": false,
   "package": /* 📦 */ "./package.json",
   "reporter": /* 📋 */ "spec",
   "slow": 75,

example/config/.mocharc.yml

@@ -28,7 +28,7 @@ ignore:
 inline-diffs: false
 # needs to be used with grep or fgrep
 # invert: false
-opts: './test/mocha.opts'
+opts: false
 recursive: false
 reporter: spec
 reporter-option:

lib/cli/options.js

@@ -15,6 +15,7 @@ const mocharc = require('../mocharc.json');
 const {list} = require('./run-helpers');
 const {loadConfig, findConfig} = require('./config');
 const findUp = require('find-up');
+const {deprecate} = require('../utils');
 const debug = require('debug')('mocha:cli:options');
 const {isNodeFlag} = require('./node-flags');
 
@@ -196,6 +197,9 @@ const loadMochaOpts = (args = {}) => {
   // if there's an exception to catch here, I'm not sure what it is.
   // by attaching the `no-opts` arg, we avoid re-parsing of `mocha.opts`.
   if (mochaOpts) {
+    deprecate(
+      'Configuration via mocha.opts is DEPRECATED and will be removed from a future version of Mocha. Use RC files or package.json instead.'
+    );
     result = parse(parseMochaOpts(mochaOpts));
     debug(`${filepath} parsed succesfully`);
   }

lib/cli/run.js

@@ -166,7 +166,7 @@ exports.builder = yargs =>
       },
       opts: {
         default: defaults.opts,
-        description: 'Path to `mocha.opts`',
+        description: 'Path to `mocha.opts` (DEPRECATED)',
         group: GROUPS.CONFIG,
         normalize: true,
         requiresArg: true

test/integration/options/opts.spec.js

@@ -10,6 +10,24 @@ describe('--opts', function() {
   var args = [];
   var fixture = path.join('options', 'opts');
 
+  it('should print a deprecation warning', function(done) {
+    var mochaOpts = path.join('test', 'opts', 'mocha.opts');
+    args = [resolvePath(fixture), '--opts', mochaOpts];
+    invokeMocha(
+      args,
+      function(err, res) {
+        if (err) {
+          return done(err);
+        }
+
+        expect(res, 'to have passed');
+        expect(res.output, 'to contain', 'mocha.opts is DEPRECATED');
+        done();
+      },
+      'pipe'
+    );
+  });
+
   it('should work despite nonexistent default options file', function(done) {
     args = [];
     runMochaJSON(fixture, args, function(err, res) {