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

jasnell · jasnell · commit 4c5a6c3feb97 · 2016-04-13T09:09:59.000-07:00
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
diff --git a/doc/api/console.markdown b/doc/api/console.markdown
@@ -109,6 +109,45 @@ console.assert(false, 'Whoops %s', 'didn\'t work');
   // AssertionError: Whoops didn't work
 ```
 
+It is important to note that the `console.assert()` method in Node.js is
+implemented differently than the `console.assert()` method available in
+browsers. 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`.
