feat: Support unhandled rejections by default (#1242)

Author: kamilogorek

docs/config.rst

@@ -227,6 +227,11 @@ Those configuration options are documented below:
     By default, Raven captures as many as 100 breadcrumb entries. If you find this too noisy, you can reduce this
     number by setting `maxBreadcrumbs`. Note that this number cannot be set higher than the default of 100.
 
+.. describe:: captureUnhandledRejections
+
+    By default, Raven captures all unhandled promise rejections using standard ``unhandledrejection`` event.
+    If you want to disable this behaviour, set this option to ``false``.
+
 .. describe:: transport
 
     Override the default HTTP data transport handler.

docs/usage.rst

@@ -333,11 +333,11 @@ And set an ``Access-Control-Allow-Origin`` HTTP header on that file.
 Promises
 --------
 
-By default, Raven.js does not capture unhandled promise rejections.
+By default, Raven.js capture unhandled promise rejections as described in official ECMAScript 6 standard.
 
-Most Promise libraries have a global hook for capturing unhandled errors. You will need to
-manually hook into such an event handler and call ``Raven.captureException`` or ``Raven.captureMessage``
-directly.
+Most Promise libraries however, have a global hook for capturing unhandled errors. You may want to disable default behaviour
+by setting ``captureUnhandledRejections`` option to ``false`` and manually hook into such event handler
+and call ``Raven.captureException`` or ``Raven.captureMessage`` directly.
 
 For example, the `RSVP.js library
 <https://github.com/tildeio/rsvp.js/>`_ (used by Ember.js) allows you to bind an event handler to a `global error event
@@ -350,13 +350,8 @@ For example, the `RSVP.js library
     });
 
 `Bluebird
-<http://bluebirdjs.com/>`_ and other promise libraries report unhandled rejections to a global DOM event, ``unhandledrejection``:
-
-.. code-block:: javascript
-
-    window.onunhandledrejection = function(evt) {
-        Raven.captureException(evt.reason);
-    };
+<http://bluebirdjs.com/>`_ and other promise libraries report unhandled rejections to a global DOM event, ``unhandledrejection``.
+In this case, you don't need to do anything, we've already got you covered by with default ``captureUnhandledRejections: true`` setting.
 
 Please consult your promise library documentation on how to hook into its global unhandled rejection handler, if it exposes one.
 

src/raven.js

@@ -79,6 +79,7 @@ function Raven() {
     includePaths: [],
     headers: null,
     collectWindowErrors: true,
+    captureUnhandledRejections: true,
     maxMessageLength: 0,
 
     // By default, truncates URL values to 250 chars
@@ -237,6 +238,10 @@ Raven.prototype = {
         self._handleOnErrorStackInfo.apply(self, arguments);
       });
 
+      if (self._globalOptions.captureUnhandledRejections) {
+        self._attachPromiseRejectionHandler();
+      }
+
       self._patchFunctionToString();
 
       if (self._globalOptions.instrument && self._globalOptions.instrument.tryCatch) {
@@ -387,14 +392,15 @@ Raven.prototype = {
     return wrapped;
   },
 
-  /*
-     * Uninstalls the global error handler.
-     *
-     * @return {Raven}
-     */
+  /**
+   * Uninstalls the global error handler.
+   *
+   * @return {Raven}
+   */
   uninstall: function() {
     TraceKit.report.uninstall();
 
+    this._detachPromiseRejectionHandler();
     this._unpatchFunctionToString();
     this._restoreBuiltIns();
     this._restoreConsole();
@@ -405,13 +411,47 @@ Raven.prototype = {
     return this;
   },
 
-  /*
-     * Manually capture an exception and send it over to Sentry
-     *
-     * @param {error} ex An exception to be logged
-     * @param {object} options A specific set of options for this error [optional]
-     * @return {Raven}
-     */
+  /**
+   * Callback used for `unhandledrejection` event
+   *
+   * @param {PromiseRejectionEvent} event An object containing
+   *   promise: the Promise that was rejected
+   *   reason: the value with which the Promise was rejected
+   * @return void
+   */
+  _promiseRejectionHandler: function(event) {
+    this._logDebug('debug', 'Raven caught unhandled promise rejection:', event);
+    this.captureException(event.reason);
+  },
+
+  /**
+   * Installs the global promise rejection handler.
+   *
+   * @return {raven}
+   */
+  _attachPromiseRejectionHandler: function() {
+    this._promiseRejectionHandler = this._promiseRejectionHandler.bind(this);
+    _window.addEventListener('unhandledrejection', this._promiseRejectionHandler);
+    return this;
+  },
+
+  /**
+   * Uninstalls the global promise rejection handler.
+   *
+   * @return {raven}
+   */
+  _detachPromiseRejectionHandler: function() {
+    _window.removeEventListener('unhandledrejection', this._promiseRejectionHandler);
+    return this;
+  },
+
+  /**
+   * Manually capture an exception and send it over to Sentry
+   *
+   * @param {error} ex An exception to be logged
+   * @param {object} options A specific set of options for this error [optional]
+   * @return {Raven}
+   */
   captureException: function(ex, options) {
     options = objectMerge({trimHeadFrames: 0}, options ? options : {});
     // Cases for sending ex as a message, rather than an exception

src/utils.js

@@ -97,6 +97,10 @@ function supportsReferrerPolicy() {
   }
 }
 
+function supportsPromiseRejectionEvent() {
+  return typeof PromiseRejectionEvent === 'function';
+}
+
 function wrappedCallback(callback) {
   function dataCallback(data, original) {
     var normalizedData = callback(data) || data;
@@ -450,6 +454,7 @@ module.exports = {
   supportsErrorEvent: supportsErrorEvent,
   supportsFetch: supportsFetch,
   supportsReferrerPolicy: supportsReferrerPolicy,
+  supportsPromiseRejectionEvent: supportsPromiseRejectionEvent,
   wrappedCallback: wrappedCallback,
   each: each,
   objectMerge: objectMerge,

test/raven.test.js

@@ -25,6 +25,7 @@ var joinRegExp = utils.joinRegExp;
 var supportsErrorEvent = utils.supportsErrorEvent;
 var supportsFetch = utils.supportsFetch;
 var supportsReferrerPolicy = utils.supportsReferrerPolicy;
+var supportsPromiseRejectionEvent = utils.supportsPromiseRejectionEvent;
 
 // window.console must be stubbed in for browsers that don't have it
 if (typeof window.console === 'undefined') {
@@ -756,6 +757,40 @@ describe('globals', function() {
     });
   });
 
+  if (supportsPromiseRejectionEvent()) {
+    describe('captureUnhandledRejections', function() {
+      it('should capture string rejections', function(done) {
+        Raven._attachPromiseRejectionHandler();
+
+        this.sinon.stub(Raven, 'captureException').callsFake(function(reason) {
+          assert.equal(reason, 'foo');
+          Raven._detachPromiseRejectionHandler();
+          done();
+        });
+
+        new Promise(function(resolve, reject) {
+          reject('foo');
+        });
+      });
+
+      it('should capture error rejections', function(done) {
+        var err = new Error('foo');
+
+        Raven._attachPromiseRejectionHandler();
+
+        this.sinon.stub(Raven, 'captureException').callsFake(function(reason) {
+          assert.equal(reason, err);
+          Raven._detachPromiseRejectionHandler();
+          done();
+        });
+
+        new Promise(function(resolve, reject) {
+          reject(err);
+        });
+      });
+    });
+  }
+
   describe('send', function() {
     it('should build a good data payload', function() {
       this.sinon.stub(Raven, 'isSetup').returns(true);
@@ -2347,6 +2382,29 @@ describe('Raven (public API)', function() {
       });
     });
 
+    describe('captureUnhandledRejections', function() {
+      it('should be true by default', function() {
+        Raven.config(SENTRY_DSN);
+        assert.isTrue(Raven._globalOptions.captureUnhandledRejections);
+      });
+
+      it('should be true if set to true', function() {
+        Raven.config(SENTRY_DSN, {
+          captureUnhandledRejections: true
+        });
+
+        assert.isTrue(Raven._globalOptions.captureUnhandledRejections);
+      });
+
+      it('should be false if set to false', function() {
+        Raven.config(SENTRY_DSN, {
+          captureUnhandledRejections: false
+        });
+
+        assert.isFalse(Raven._globalOptions.captureUnhandledRejections);
+      });
+    });
+
     describe('maxBreadcrumbs', function() {
       it('should override the default', function() {
         Raven.config(SENTRY_DSN, {maxBreadcrumbs: 50});

test/vendor/tracekit.test.js

@@ -181,9 +181,7 @@ describe('TraceKit', function() {
     });
 
     describe('when no 5th argument (error object)', function() {
-      it('should seperate name, message for default error types (e.g. ReferenceError)', function(
-        done
-      ) {
+      it('should seperate name, message for default error types (e.g. ReferenceError)', function(done) {
         subscriptionHandler = function(stackInfo, extra) {
           assert.equal(stackInfo.name, 'ReferenceError');
           assert.equal(stackInfo.message, 'foo is undefined');
@@ -203,9 +201,7 @@ describe('TraceKit', function() {
         done();
       });
 
-      it('should separate name, message for default error types on Opera Mini (see #546)', function(
-        done
-      ) {
+      it('should separate name, message for default error types on Opera Mini (see #546)', function(done) {
         subscriptionHandler = function(stackInfo, extra) {
           assert.equal(stackInfo.name, 'ReferenceError');
           assert.equal(stackInfo.message, 'Undefined variable: foo');