Merge branch 'growl' of https://github.com/plroebuck/mocha into growl

.eslintignore

@@ -2,4 +2,5 @@ coverage/
 mocha.js
 *.fixture.js
 docs/
+out/
 !lib/mocha.js

.gitignore

@@ -22,4 +22,5 @@ yarn.lock
 docs/_site
 docs/_dist
 docs/api
+out/
 .vscode/

.ruby-version

@@ -0,0 +1 @@
+2.4.3

.travis.yml

@@ -1,3 +1,7 @@
+###
+### .travis.yml
+###
+
 # these are executed in order.  each must pass for the next to be run
 stages:
   - smoke # this ensures a "user" install works properly
@@ -7,7 +11,11 @@ stages:
 
 # defaults
 language: node_js
-node_js: '10'
+node_js: '11'
+addons:
+  apt:
+    packages:
+    - libnotify-bin
 # `nvm install` happens before the cache is restored, which means
 # we must install our own npm elsewhere (`~/npm`)
 before_install: |
@@ -32,7 +40,7 @@ jobs:
 
     - &node
       script: npm start test.node
-      node_js: '9'
+      node_js: '10'
 
     - <<: *node
       node_js: '8'
@@ -67,7 +75,7 @@ jobs:
           - node_modules # npm install, unlike npm ci, doesn't wipe node_modules
 
     - <<: *smoke
-      node_js: '9'
+      node_js: '10'
 
     - <<: *smoke
       node_js: '8'

Gemfile

@@ -1,3 +1,3 @@
 source "https://rubygems.org"
 # Added at 2017-12-05 23:01:55 -0800 by boneskull:
-gem "jekyll", "~> 3.6"
+gem "jekyll", ">= 3.8.4"

Gemfile.lock

@@ -14,7 +14,7 @@ GEM
     http_parser.rb (0.6.0)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    jekyll (3.8.3)
+    jekyll (3.8.4)
       addressable (~> 2.4)
       colorator (~> 1.0)
       em-websocket (~> 0.5)
@@ -29,25 +29,25 @@ GEM
       safe_yaml (~> 1.0)
     jekyll-sass-converter (1.5.2)
       sass (~> 3.4)
-    jekyll-watch (2.0.0)
+    jekyll-watch (2.1.2)
       listen (~> 3.0)
     kramdown (1.17.0)
-    liquid (4.0.0)
+    liquid (4.0.1)
     listen (3.1.5)
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
       ruby_dep (~> 1.2)
     mercenary (0.3.6)
-    pathutil (0.16.1)
+    pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (3.0.3)
     rb-fsevent (0.10.3)
     rb-inotify (0.9.10)
       ffi (>= 0.5.0, < 2)
-    rouge (3.2.1)
+    rouge (3.3.0)
     ruby_dep (1.5.0)
     safe_yaml (1.0.4)
-    sass (3.5.7)
+    sass (3.6.0)
       sass-listen (~> 4.0.0)
     sass-listen (4.0.0)
       rb-fsevent (~> 0.9, >= 0.9.4)
@@ -57,7 +57,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  jekyll (~> 3.6)
+  jekyll (>= 3.8.4)
 
 BUNDLED WITH
-   1.16.1
+   1.16.6

MAINTAINERS.md

@@ -279,18 +279,16 @@ This is not necessarily ideal, and we should consider another method of using br
 1. Decide whether this is a `patch`, `minor`, or `major` release by the PRs which have been merged since the last release.
 1. Checkout `master` in your working copy & pull.
 1. Modify `CHANGELOG.md`; follow the existing conventions in that file.  Commit this file only; add `[ci skip]` to the commit message to avoid a build.
-1. Use `npm version` to bump the version; see `npm version --help` for more info.  (Hint--use `-m`: e.g. `npm version patch -m 'Release v%s'`)
-1. Push `master` to origin with your new tag; e.g. `git push origin master --tags`
+1. Use `npm version` (use `npm@6+`) to bump the version; see `npm version --help` for more info.  (Hint--use `-m`: e.g., `npm version patch -m 'Release v%s'`)
+1. Push `master` to `origin` with your new tag; e.g. `git push origin master --tags`
 1. Copy & paste the added lines to a new GitHub "release".  Be sure to add any missing link references (use "preview" button).  Save release as draft.
 1. Meanwhile, you can check [the build](https://travis-ci.org/mochajs/mocha) on Travis-CI.
-1. Once it's green and you're satisfied with the release notes, open your draft release on GitHub, then click "publish"
+1. Once the build is green, and you're satisfied with the release notes, open your draft release on GitHub, then click "publish."
 1. Back in your working copy, run `npm publish`.
-1. Announce the update on Twitter or just tell your dog or something.
+1. Announce the update on Twitter or just tell your dog or something.  New releases will be automatically tweeted by [@b0neskull](https://twitter.com/b0neskull).
 
 *Note: there are too many steps above.*
 
-> As of this writing, `npm version` (using npm@5) is not working well, and you may have to tag manually.  Commit the change to the version in `package.json` with a message of the format `Release vX.Y.Z`, then tag the changeset using `vX.Y.Z`.
-
 ## Projects
 
 There are [Projects](https://github.com/mochajs/mocha/projects), but we haven't yet settled on how to use them.

appveyor.yml

@@ -1,27 +1,71 @@
-platform:
-  - x64
+###
+### appveyor.yml
+###
+
+## General configuration
+version: '{build}'
+skip_commits:
+  message: /\[ci\s+skip\]/
+
+## Environment configuration
+shallow_clone: true
+clone_depth: 1
 environment:
   matrix:
+    - nodejs_version: '11'
     - nodejs_version: '10'
-    - nodejs_version: '9'
     - nodejs_version: '8'
     - nodejs_version: '6'
+matrix:
+  fast_finish: true
 install:
+  ## Manual Growl install
+  - ps: Add-AppveyorMessage "Installing Growl..."
+  - ps: $exePath = "$($env:USERPROFILE)\GrowlInstaller.exe"
+  - ps: (New-Object Net.WebClient).DownloadFile('http://www.growlforwindows.com/gfw/downloads/GrowlInstaller.exe', $exePath)
+  - ps: mkdir C:\GrowlInstaller | out-null
+  - ps: 7z x $exePath -oC:\GrowlInstaller | out-null
+  - ps: cmd /c start /wait msiexec /i C:\GrowlInstaller\Growl_v2.0.msi /quiet
+  - ps: $env:path = "C:\Program Files (x86)\Growl for Windows;$env:path"
+  ## Node-related installs
+  - ps: Add-AppveyorMessage "Installing Node..."
+  - set PATH=%APPDATA%\npm;C:\MinGW\bin;%PATH%
   - ps: Install-Product node $env:nodejs_version x64
-  - set CI=true
-  - set PATH=%APPDATA%\npm;c:\MinGW\bin;%PATH%
+  - ps: Add-AppveyorMessage "Installing npm..."
   - npm install -g npm@^5
+  ## Mocha-related package installs
+  - ps: Add-AppveyorMessage "Installing Mocha dependencies..."
   - npm ci --ignore-scripts
-matrix:
-  fast_finish: true
-build: off
-version: '{build}'
-shallow_clone: true
-clone_depth: 1
+
+## Build configuration
+platform:
+  - x64
+build: script
+before_build:
+  ## Growl requires some time before it's ready to handle notifications
+  - ps: Start-Process -NoNewWindow Growl
+  - ps: Add-AppveyorMessage "Started Growl service..."
+  - ps: Start-Sleep -Milliseconds 2000
+build_script:
+  ## Placeholder command
+  - ps: Start-Sleep -Milliseconds 0
+  #- ps: Add-AppveyorMessage "Verify Growl responding..."
+  #- ps: growlnotify test
+
+## Test configuration
+before_test:
+  - set CI=true
 test_script:
+  - ps: Add-AppveyorMessage "Displaying version information"
   - node --version
   - npm --version
+  - ps: Add-AppveyorMessage "Running tests..."
   - npm start test.node
-skip_commits:
-  message: /\[ci\s+skip\]/
+  - ps: Add-AppveyorMessage "Done"
 
+## Notifications
+notifications:
+  - provider: Email
+    on_build_success: false
+    on_build_failure: false
+    on_build_status_changed: false

bin/_mocha

@@ -157,9 +157,17 @@ program
   .option('-f, --fgrep <string>', 'only run tests containing <string>')
   .option('-gc, --expose-gc', 'expose gc extension')
   .option('-i, --invert', 'inverts --grep and --fgrep matches')
-  .option('-r, --require <name>', 'require the given module')
-  .option('-s, --slow <ms>', '"slow" test threshold in milliseconds [75]')
-  .option('-t, --timeout <ms>', 'set test-case timeout in milliseconds [2000]')
+  .option('-r, --require <name>', 'require the given module', [])
+  .option(
+    '-s, --slow <ms>',
+    'specify "slow" test threshold in milliseconds',
+    75
+  )
+  .option(
+    '-t, --timeout <ms>',
+    'specify test timeout threshold in milliseconds',
+    2000
+  )
   .option(
     '-u, --ui <name>',
     `specify user-interface (${interfaceNames.join('|')})`,
@@ -204,24 +212,28 @@ program
     '--inspect-brk',
     'activate devtools in chrome and break on the first line'
   )
-  .option('--interfaces', 'display available interfaces')
+  .option('--interfaces', 'output provided interfaces and exit')
   .option('--no-deprecation', 'silence deprecation warnings')
   .option(
     '--exit',
     'force shutdown of the event loop after test run: mocha will call process.exit'
   )
-  .option('--no-timeouts', 'disables timeouts, given implicitly with --debug')
+  .option(
+    '--no-timeouts',
+    'disables timeouts, given implicitly with --debug/--inspect'
+  )
   .option('--no-warnings', 'silence all node process warnings')
   .option('--opts <path>', 'specify opts path', 'test/mocha.opts')
   .option('--perf-basic-prof', 'enable perf linux profiler (basic support)')
   .option('--napi-modules', 'enable experimental NAPI modules')
   .option('--prof', 'log statistical profiling information')
   .option('--log-timer-events', 'Time events including external callbacks')
   .option('--recursive', 'include sub directories')
-  .option('--reporters', 'display available reporters')
+  .option('--reporters', 'output provided reporters and exit')
   .option(
     '--retries <times>',
-    'set numbers of time to retry a failed test case'
+    'specify number of times to retry a failed test case',
+    0
   )
   .option(
     '--throw-deprecation',
@@ -246,11 +258,16 @@ program
   )
   .option(
     '--file <file>',
-    'include a file to be ran during the suite',
+    'adds file be loaded prior to suite execution',
     collect,
     []
   )
-  .option('--exclude <file>', 'a file or glob pattern to ignore', collect, []);
+  .option(
+    '--exclude <file>',
+    'adds file or glob pattern to ignore',
+    collect,
+    []
+  );
 
 program._name = 'mocha';
 

bin/options.js

@@ -13,9 +13,54 @@ const fs = require('fs');
 module.exports = getOptions;
 
 /**
- * Get options.
+ * Default pathname for run-control file.
+ *
+ * @constant
+ * @type {string}
+ * @default
  */
+const defaultPathname = 'test/mocha.opts';
 
+/**
+ * Reads contents of the run-control file.
+ *
+ * @private
+ * @param {string} pathname - Pathname of run-control file.
+ * @returns {string} file contents
+ */
+function readOptionsFile(pathname) {
+  return fs.readFileSync(pathname, 'utf8');
+}
+
+/**
+ * Parses options read from run-control file.
+ *
+ * @private
+ * @param {string} content - Content read from run-control file.
+ * @returns {string[]} cmdline options (and associated arguments)
+ */
+function parseOptions(content) {
+  /*
+   * Replaces comments with empty strings
+   * Replaces escaped spaces (e.g., 'xxx\ yyy') with HTML space
+   * Splits on whitespace, creating array of substrings
+   * Filters empty string elements from array
+   * Replaces any HTML space with space
+   */
+  return content
+    .replace(/^#.*$/gm, '')
+    .replace(/\\\s/g, '%20')
+    .split(/\s/)
+    .filter(Boolean)
+    .map(value => value.replace(/%20/g, ' '));
+}
+
+/**
+ * Prepends options from run-control file to the command line arguments.
+ *
+ * @public
+ * @see {@link https://mochajs.org/#mochaopts|mocha.opts}
+ */
 function getOptions() {
   if (
     process.argv.length === 3 &&
@@ -26,17 +71,11 @@ function getOptions() {
 
   const optsPath =
     process.argv.indexOf('--opts') === -1
-      ? 'test/mocha.opts'
+      ? defaultPathname
       : process.argv[process.argv.indexOf('--opts') + 1];
 
   try {
-    const opts = fs
-      .readFileSync(optsPath, 'utf8')
-      .replace(/^#.*$/gm, '')
-      .replace(/\\\s/g, '%20')
-      .split(/\s/)
-      .filter(Boolean)
-      .map(value => value.replace(/%20/g, ' '));
+    const opts = parseOptions(readOptionsFile(optsPath));
 
     process.argv = process.argv
       .slice(0, 2)