From 3bc31526bba6845221f53b89b397a77a27ab07d7 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Tue, 12 Apr 2016 11:27:29 -0700
Subject: [PATCH] doc: explain differences in console.assert between node and
 browsers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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

This "fixes" https://github.com/nodejs/node/issues/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: https://github.com/nodejs/node/issues/5340
PR-URL: https://github.com/nodejs/node/pull/6169
Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com>
Reviewed-By: Jeff Harris <@techjeffharris>
---
 doc/api/console.markdown | 41 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/doc/api/console.markdown b/doc/api/console.markdown
index 6cf5051af2591e..655e64c5ac9f01 100644
--- a/doc/api/console.markdown
+++ b/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