doc: explain differences in console.assert between node and browsers

Provide an example for implementing browser like behavior for console.assert.

This "fixes" #5340 by providing an
alternative to changing Node.js' implemented behavior. Instead, we
document the differences and show how to work around them if
browser like semantics are desired.

Fixes: #5340
PR-URL: #6169
Reviewed-By: Robert Jefe Lindstädt <[email protected]>
Reviewed-By: Jeff Harris <@techjeffharris>

Author: jasnell

doc/api/console.markdown

@@ -109,6 +109,46 @@ console.assert(false, 'Whoops %s', 'didn\'t work');
   // AssertionError: Whoops didn't work
 ```
 
+*Note: the `console.assert()` method is implemented differently in Node.js
+than the `console.assert()` method [available in browsers][web-api-assert].*
+
+Specifically, in browsers, calling `console.assert()` with a falsy
+assertion will cause the `message` to be printed to the console without
+interrupting execution of subsequent code. In Node.js, however, a falsy
+assertion will cause an `AssertionError` to be thrown.
+
+Functionality approximating that implemented by browsers can be implemented
+by extending Node.js' `console` and overriding the `console.assert()` method.
+
+In the following example, a simple module is created that extends and overrides
+the default behavior of `console` in Node.js.
+
+```js
+'use strict';
+
+// Creates a simple extension of console with a
+// new impl for assert without monkey-patching.
+const myConsole = Object.setPrototypeOf({
+  assert(assertion, message, ...args) {
+    try {
+      console.assert(assertion, message, ...args);
+    } catch (err) {
+      console.error(err.stack);
+    }
+  }
+}, console);
+
+module.exports = myConsole;
+```
+
+This can then be used as a direct replacement for the built in console:
+
+```js
+const console = require('./myConsole');
+console.assert(false, 'this message will print, but no error thrown');
+console.log('this will also print');
+```
+
 ### console.dir(obj[, options])
 
 Uses [`util.inspect()`][] on `obj` and prints the resulting string to `stdout`.
@@ -224,3 +264,4 @@ The `console.warn()` function is an alias for [`console.error()`][].
 [`util.format()`]: util.html#util_util_format_format
 [`util.inspect()`]: util.html#util_util_inspect_object_options
 [customizing `util.inspect()` colors]: util.html#util_customizing_util_inspect_colors
+[web-api-assert]: https://developer.mozilla.org/en-US/docs/Web/API/console/assert