Merge branch 'master' into remove-jekyll

* master:
  test(integration/reporters.spec.js): Add test for TAP when given invalid reporter option
  Fix couple errors missing codes (#3666)
  fix tests & formatting on windows; closes #3643
  Set "root" property on Suite correctly (#3632)
  remove invalid comment; see #1962
  fix WallabyJS config [ci skip]
  mega-upgrade of .gitignore [ci skip]
  Update documentation concerning fs.readdir (#3657)
  Add test for Runner event order (#3642)

# Conflicts:
#	.gitignore
#	.wallaby.js

.gitignore

@@ -1,25 +1,143 @@
-.DS_Store
-node_modules
-*.sock
-*.sw*
-.idea
-*.iml
-*.patch
-*.diff
-npm-debug.log*
-.envrc
+# Mocha-specific
+docs/_site
+docs/_dist
+mocha.js
 .karma/
+!lib/mocha.js
+
+#########################################
+# NON-MOCHA STUFF GOES BELOW THIS THING #
+#########################################
+
+# Git mergetool
+# Use `git config mergetool.keepBackup false` to stop generating these files
 *.orig
-.nyc_output/
-coverage/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# nyc/istanbul
+coverage
+.nyc_output
+
+# Dependencies
+node_modules/
+
+# npm
+.npm
+*.tgz
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# dotenv environment variables file
+.env
+.env.test
+
+# Yarn
 yarn.lock
-/mocha.js
-# artifacts from various diff tools
+.yarn-integrity
+
+# Various temporary files
+*~
+
+# Emacs
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Vim
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+Session.vim
+[._]*.un~
+
+# Diff
+*.patch
+*.diff
+
+# VSCode
+.vscode/
+
+# JetBrains' IDEs
+.idea/
+*.iws
+out/
+.idea_modules/
+atlassian-ide-plugin.xml
+
+# SourceTree
 *_BACKUP_*
 *_BASE_*
 *_LOCAL_*
 *_REMOTE_*
-docs/_site
-docs/_dist
-out/
-.vscode/
+
+# SublimeText
+*.tmlanguage.cache
+*.tmPreferences.cache
+*.stTheme.cache
+*.sublime-workspace
+*.sublime-project
+sftp-config.json
+Package Control.last-run
+Package Control.ca-list
+Package Control.ca-bundle
+Package Control.system-ca-bundle
+Package Control.cache/
+Package Control.ca-certs/
+Package Control.merged-ca-bundle
+Package Control.user-ca-bundle
+oscrypto-ca-bundle.crt
+bh_unicode_properties.cache
+GitHub.sublime-settings
+
+# direnv
+.envrc
+
+# Linux
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*
+
+# Windows
+Thumbs.db
+ehthumbs.db
+ehthumbs_vista.db
+*.stackdump
+[Dd]esktop.ini
+$RECYCLE.BIN/
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+*.lnk
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# SauceConnect
+*.sock

.wallaby.js

@@ -17,13 +17,13 @@ module.exports = () => {
       },
       'package.json',
       'test/opts/mocha.opts',
-      'mocharc.yml',
-      '!lib/browser/**/*.js'
+      'mocharc.yml'
     ],
     filesWithNoCoverageCalculated: [
       'test/**/*.fixture.js',
       'test/setup.js',
-      'test/assertions.js'
+      'test/assertions.js',
+      'lib/browser/**/*.js'
     ],
     tests: ['test/unit/**/*.spec.js', 'test/node-unit/**/*.spec.js'],
     env: {

lib/cli/run.js

@@ -9,8 +9,10 @@
 
 const Mocha = require('../mocha');
 const ansi = require('ansi-colors');
-const errors = require('../errors');
-const createInvalidArgumentValueError = errors.createInvalidArgumentValueError;
+const {
+  createInvalidArgumentValueError,
+  createMissingArgumentError
+} = require('../errors');
 
 const {
   list,
@@ -258,13 +260,15 @@ exports.builder = yargs =>
 
       // yargs.implies() isn't flexible enough to handle this
       if (argv.invert && !('fgrep' in argv || 'grep' in argv)) {
-        throw new Error(
-          '"--invert" requires one of "--fgrep <str>" or "--grep <regexp>"'
+        throw createMissingArgumentError(
+          '"--invert" requires one of "--fgrep <str>" or "--grep <regexp>"',
+          '--fgrep|--grep',
+          'string|regexp'
         );
       }
 
       if (argv.compilers) {
-        throw new Error(
+        throw createInvalidArgumentValueError(
           `--compilers is DEPRECATED and no longer supported.
           See ${ansi.cyan('https://git.io/vdcSr')} for migration information.`
         );

lib/mocha.js

@@ -92,7 +92,7 @@ function Mocha(options) {
   this.files = [];
   this.options = options;
   // root suite
-  this.suite = new exports.Suite('', new exports.Context());
+  this.suite = new exports.Suite('', new exports.Context(), true);
 
   if ('useColors' in options) {
     utils.deprecate(

lib/suite.js

@@ -22,9 +22,7 @@ var createInvalidArgumentTypeError = errors.createInvalidArgumentTypeError;
 exports = module.exports = Suite;
 
 /**
- * Create a new `Suite` with the given `title` and parent `Suite`. When a suite
- * with the same title is already present, that suite is returned to provide
- * nicer reporter and more flexible meta-testing.
+ * Create a new `Suite` with the given `title` and parent `Suite`.
  *
  * @memberof Mocha
  * @public
@@ -41,15 +39,18 @@ exports.create = function(parent, title) {
 };
 
 /**
- * Initialize a new `Suite` with the given `title` and `ctx`. Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
+ * Constructs a new `Suite` instance with the given `title`, `ctx`, and `isRoot`.
  *
- * @memberof Mocha
  * @public
  * @class
- * @param {string} title
- * @param {Context} parentContext
+ * @extends EventEmitter
+ * @memberof Mocha
+ * @see {@link https://nodejs.org/api/events.html#events_class_eventemitter|EventEmitter}
+ * @param {string} title - Suite title.
+ * @param {Context} parentContext - Parent context instance.
+ * @param {boolean} [isRoot=false] - Whether this is the root suite.
  */
-function Suite(title, parentContext) {
+function Suite(title, parentContext, isRoot) {
   if (!utils.isString(title)) {
     throw createInvalidArgumentTypeError(
       'Suite argument "title" must be a string. Received type "' +
@@ -70,7 +71,7 @@ function Suite(title, parentContext) {
   this._beforeAll = [];
   this._afterEach = [];
   this._afterAll = [];
-  this.root = !title;
+  this.root = isRoot === true;
   this._timeout = 2000;
   this._enableTimeouts = true;
   this._slow = 75;
@@ -326,6 +327,7 @@ Suite.prototype.afterEach = function(title, fn) {
  */
 Suite.prototype.addSuite = function(suite) {
   suite.parent = this;
+  suite.root = false;
   suite.timeout(this.timeout());
   suite.retries(this.retries());
   suite.enableTimeouts(this.enableTimeouts());

lib/utils.js

@@ -83,6 +83,10 @@ function ignored(path) {
 /**
  * Lookup files in the given `dir`.
  *
+ * @description
+ * Filenames are returned in _traversal_ order by the OS/filesystem.
+ * **Make no assumption that the names will be sorted in any fashion.**
+ *
  * @private
  * @param {string} dir
  * @param {string[]} [ext=['.js']]
@@ -502,12 +506,16 @@ exports.canonicalize = function canonicalize(value, stack, typeHint) {
 /**
  * Lookup file names at the given `path`.
  *
- * @memberof Mocha.utils
+ * @description
+ * Filenames are returned in _traversal_ order by the OS/filesystem.
+ * **Make no assumption that the names will be sorted in any fashion.**
+ *
  * @public
- * @param {string} filepath Base path to start searching from.
- * @param {string[]} extensions File extensions to look for.
- * @param {boolean} recursive Whether or not to recurse into subdirectories.
+ * @memberof Mocha.utils
  * @todo Fix extension handling
+ * @param {string} filepath - Base path to start searching from.
+ * @param {string[]} extensions - File extensions to look for.
+ * @param {boolean} recursive - Whether to recurse into subdirectories.
  * @return {string[]} An array of paths.
  */
 exports.lookupFiles = function lookupFiles(filepath, extensions, recursive) {