mochajs · plroebuck · Dec 23, 2018 · Nov 1, 2018 · Nov 1, 2018 · Nov 1, 2018
diff --git a/docs/index.md b/docs/index.md
@@ -26,7 +26,7 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js](https://n
 - [async test timeout support](#delayed-root-suite)
 - [test retry support](#retry-tests)
 - [test-specific timeouts](#test-level)
-- [growl notification support](#mochaopts)
+- [Growl support](#desktop-notification-support)
 - [reports test durations](#test-duration)
 - [highlights slow tests](#dot-matrix)
 - [file watcher support](#min)
@@ -70,6 +70,7 @@ Mocha is a feature-rich JavaScript test framework running on [Node.js](https://n
 - [Interfaces](#interfaces)
 - [Reporters](#reporters)
 - [Running Mocha in the Browser](#running-mocha-in-the-browser)
+- [Desktop Notification Support](#desktop-notification-support)
 - [Configuring Mocha (Node.js)](#configuring-mocha-nodejs)
 - [`mocha.opts`](#mochaopts)
 - [The `test/` Directory](#the-test-directory)
@@ -1487,20 +1488,22 @@ A typical setup might look something like the following, where we call `mocha.se
 <head>
   <meta charset="utf-8">
   <title>Mocha Tests</title>
-  <link href="https://unpkg.com/mocha@5.2.0/mocha.css" rel="stylesheet" />
+  <link href="https://unpkg.com/mocha@6.0.0/mocha.css" rel="stylesheet" />
 </head>
 <body>
   <div id="mocha"></div>
 
   <script src="https://unpkg.com/chai/chai.js"></script>
-  <script src="https://unpkg.com/mocha@5.2.0/mocha.js"></script>
+  <script src="https://unpkg.com/mocha@6.0.0/mocha.js"></script>
 
-  <script>mocha.setup('bdd')</script>
+  <script class="mocha-init">
+    mocha.setup('bdd');
+    mocha.checkLeaks();
+  </script>
   <script src="test.array.js"></script>
   <script src="test.object.js"></script>
   <script src="test.xhr.js"></script>
-  <script>
-    mocha.checkLeaks();
+  <script class="mocha-exec">
     mocha.run();
   </script>
 </body>
@@ -1547,6 +1550,69 @@ The "HTML" reporter is what you see when running Mocha in the browser.  It looks
 
 [Mochawesome](https://www.npmjs.com/package/mochawesome) is a great alternative to the default HTML reporter.
 
+## Desktop Notification Support
+
+Desktop notifications allow asynchronous communication of events without
+forcing you to react to a notification immediately. Their appearance
+and specific functionality vary across platforms. They typically disappear
+automatically after a short delay, but their content is often stored in some
+manner that allows you to access past notifications.
+
+[Growl][] was an early notification system implementation for OS X and Windows,
+hence, the name of Mocha's `--growl` option.
+
+Once enabled, when your root suite completes test execution, a desktop
+notification should appear informing you whether your tests passed or failed.
+
+### Node-based notifications
+
+In order to use desktop notifications with the command-line interface (CLI),
+you **must** first install some platform-specific prerequisite software.
+Instructions for doing so can be found [here](https://github.com/mochajs/mocha/wiki/Growl-Notifications).
+
+Enable Mocha's desktop notifications as follows:
+
+```bash
+$ mocha --growl
+```
+
+### Browser-based notifications
+
+Web notification support is being made available for current versions of
+modern browsers. Ensure your browser version supports both
+[promises](https://caniuse.com/#feat=promises) and
+[web notifications](https://caniuse.com/#feat=notifications). As the
+Notification API evolved over time, **do not expect** the minimum possible
+browser version to necessarily work.
+
+Enable Mocha's web notifications with a slight modification to your
+client-side mocha HTML. Add a call to `mocha.growl()` prior to running your
+tests as shown below:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Mocha</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="stylesheet" href="https://unpkg.com/[email protected]/mocha.css" />
+  </head>
+  <body>
+    <div id="mocha"></div>
+    <script src="https://unpkg.com/[email protected]/mocha.js"></script>
+    <script class="mocha-init">
+      mocha.setup('bdd');
+      mocha.growl();      // <-- Enables web notifications
+    </script>
+    <script src="tests.js"></script>
+    <script class="mocha-exec">
+      mocha.run();
+    </script>
+  </body>
+</html>
+```
+
 ## Configuring Mocha (Node.js)
 
 > *New in v6.0.0*
@@ -1631,11 +1697,11 @@ For example, suppose you have the following `mocha.opts` file:
 
 The settings above will default the reporter to `dot`, require the `should`
 library, and use `bdd` as the interface. With this, you may then invoke `mocha`
-with additional arguments, here enabling [Growl](http://growl.info/) support,
-and changing the reporter to `list`:
+with additional arguments, here changing the reporter to `list` and setting the
+slow threshold to half a second:
 
 ```sh
-$ mocha --reporter list --growl
+$ mocha --reporter list --slow 500
 ```
 
 To ignore your `mocha.opts`, use the `--no-opts` option.
@@ -1727,7 +1793,20 @@ $ REPORTER=nyan npm test
 
 ## More Information
 
-In addition to chatting with us on [Gitter], for additional information such as using spies, mocking, and shared behaviours be sure to check out the [Mocha Wiki](https://github.com/mochajs/mocha/wiki) on GitHub. For discussions join the [Google Group](https://groups.google.com/group/mochajs). For a running example of Mocha, view [example/tests.html](example/tests.html). For the JavaScript API, view the [API documentation](api/) or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js#L51).
+In addition to chatting with us on [Gitter][Gitter-mocha], for additional information such as using
+spies, mocking, and shared behaviours be sure to check out the [Mocha Wiki][Mocha-wiki] on GitHub.
+For discussions join the [Google Group][Google-mocha]. For a running example of Mocha, view
+[example/tests.html](example/tests.html). For the JavaScript API, view the [API documentation](api/)
+or the [source](https://github.com/mochajs/mocha/blob/master/lib/mocha.js).
+
+[//]: # (Cross reference section)
+
+[Gitter-mocha]: https://gitter.im/mochajs/mocha
+[Google-mocha]: https://groups.google.com/group/mochajs
+[Growl]: http://growl.info/
+[Growl-install]: https://github.com/mochajs/mocha/wiki/Growl-Notifications
+[Mocha-website]: https://mochajs.org/
+[Mocha-wiki]: https://github.com/mochajs/mocha/wiki
 
 <!-- AUTO-GENERATED-CONTENT:START (manifest:template=[Gitter]: ${gitter}) -->
 [Gitter]: https://gitter.im/mochajs/mocha

diff --git a/lib/browser/growl.js b/lib/browser/growl.js
@@ -1,5 +1,207 @@
 'use strict';
 
-// just stub out growl
+/**
+ * Web Notifications module.
+ * @module Growl
+ */
 
-module.exports = require('../utils').noop;
+/**
+ * @summary
+ * Checks if browser notification support exists.
+ *
+ * @public
+ * @see {@link https://caniuse.com/#feat=notifications|Browser support (notifications)}
+ * @see {@link https://caniuse.com/#feat=promises|Browser support (promises)}
+ * @see {@link Mocha#growl}
+ * @see {@link Mocha#isGrowlCapable}
+ * @return {boolean} whether browser notification support exists
+ */
+exports.isCapable = function() {
+  var hasNotificationSupport = 'Notification' in window;
+  var hasPromiseSupport = typeof Promise === 'function';
+  return process.browser && hasNotificationSupport && hasPromiseSupport;
+};
+
+/**
+ * Implements browser notifications as a pseudo-reporter.
+ *
+ * @public
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/notification|Notification API}
+ * @see {@link https://developers.google.com/web/fundamentals/push-notifications/display-a-notification|Displaying a Notification}
+ * @see {@link Growl#isPermitted}
+ * @see {@link Mocha#_growl}
+ * @param {Runner} runner - Runner instance.
+ */
+exports.notify = function(runner) {
+  var promise = isPermitted();
+
+  /**
+   * Attempt notification.
+   */
+  var sendNotification = function() {
+    // If user hasn't responded yet... "No notification for you!" (Seinfeld)
+    Promise.race([promise, Promise.resolve(undefined)])
+      .then(canNotify)
+      .then(function() {
+        display(runner);
+      })
+      .catch(notPermitted);
+  };
+
+  runner.once('end', sendNotification);
+};
+
+/**
+ * Checks if browser notification is permitted by user.
+ *
+ * @private
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Notification/permission|Notification.permission}
+ * @see {@link Mocha#growl}
+ * @see {@link Mocha#isGrowlPermitted}
+ * @returns {Promise<boolean>} promise determining if browser notification
+ *     permissible when fulfilled.
+ */
+function isPermitted() {
+  var permitted = {
+    granted: function allow() {
+      return Promise.resolve(true);
+    },
+    denied: function deny() {
+      return Promise.resolve(false);
+    },
+    default: function ask() {
+      return Notification.requestPermission().then(function(permission) {
+        return permission === 'granted';
+      });
+    }
+  };
+
+  return permitted[Notification.permission]();
+}
+
+/**
+ * @summary
+ * Determines if notification should proceed.
+ *
+ * @description
+ * Notification shall <strong>not</strong> proceed unless `value` is true.
+ *
+ * `value` will equal one of:
+ * <ul>
+ *   <li><code>true</code> (from `isPermitted`)</li>
+ *   <li><code>false</code> (from `isPermitted`)</li>
+ *   <li><code>undefined</code> (from `Promise.race`)</li>
+ * </ul>
+ *
+ * @private
+ * @param {boolean|undefined} value - Determines if notification permissible.
+ * @returns {Promise<undefined>} Notification can proceed
+ */
+function canNotify(value) {
+  if (!value) {
+    var why = value === false ? 'blocked' : 'unacknowledged';
+    var reason = 'not permitted by user (' + why + ')';
+    return Promise.reject(new Error(reason));
+  }
+  return Promise.resolve();
+}
+
+/**
+ * Displays the notification.
+ *
+ * @private
+ * @param {Runner} runner - Runner instance.
+ */
+function display(runner) {
+  var stats = runner.stats;
+  var symbol = {
+    cross: '\u274C',
+    tick: '\u2705'
+  };
+  var logo = require('../../package').logo;
+  var lang = 'en-US';
+  var _message;
+  var message;
+  var title;
+
+  if (stats.failures) {
+    _message = stats.failures + ' of ' + runner.total + ' tests failed';
+    message = symbol.cross + ' ' + _message;
+    title = 'Failed';
+  } else {
+    _message = stats.passes + ' tests passed in ' + stats.duration + 'ms';
+    message = symbol.tick + ' ' + _message;
+    title = 'Passed';
+  }
+
+  // Send notification
+  var options = {
+    badge: logo,
+    body: message,
+    icon: logo,
+    lang: lang,
+    name: 'mocha',
+    requireInteraction: false,
+    tag: generateTag(),
+    timestamp: Date.now()
+  };
+  var notification = new Notification(title, options);
+
+  // Autoclose after brief delay (makes various browsers act same)
+  var FORCE_DURATION = 4000;
+  setTimeout(notification.close.bind(notification), FORCE_DURATION);
+}
+
+/**
+ * As notifications are tangential to our purpose, just log the error.
+ *
+ * @private
+ * @param {Error} err - Why notification didn't happen.
+ */
+function notPermitted(err) {
+  console.error('notification error:', err.message);
+}
+
+/**
+ * Used to help distinguish notifications within a root suite run.
+ * @type {number}
+ */
+var ntags = 0;
+
+/**
+ * @summary
+ * Generates a datestamped, run-unique tag for each notification.
+ *
+ * @description
+ * Use of a tag allows notifications that represent the same conceptual event
+ * to specify as much. This implementation doesn't really bother.
+ *
+ * @private
+ * @returns {string} tag unique within a root suite execution
+ * @example
+ *
+ * generateTag();
+ * // => "mocha_results-20181117-1"
+ */
+function generateTag() {
+  return ['mocha_results', datestamp(), ++ntags].join('-');
+}
+
+/**
+ * Generates a datestamp.
+ *
+ * @private
+ * @returns {string} tag in YYYYMMDD format
+ * @example
+ *
+ * datestamp();
+ * // => "20181117"
+ */
+function datestamp() {
+  var now = new Date(Date.now());
+  var year = now.getFullYear();
+  var month = now.getMonth() + 1;
+  var day = now.getDate();
+
+  return '' + year + (month < 10 ? '0' : '') + month + day;
+}