feat: Async Loader example with tests and docs (#1334)

* feat: Async Loader with tests

* loader: Added simple build step

* loader: Async loading documentation

* loader: Use CDN and DSN dynamic variables

* loader: Defend users from ASI magic and update docs

Author: kamilogorek

docs/install.rst

@@ -8,10 +8,10 @@ So for example:
 
 .. sourcecode:: html
 
-    <script src="jquery.js"></script>
-    <script src="https://cdn.ravenjs.com/###RAVEN_VERSION###/raven.min.js" crossorigin="anonymous"></script>
-    <script>Raven.config('___PUBLIC_DSN___').install();</script>
-    <script src="app.js"></script>
+  <script src="jquery.js"></script>
+  <script src="https://cdn.ravenjs.com/###RAVEN_VERSION###/raven.min.js" crossorigin="anonymous"></script>
+  <script>Raven.config('___PUBLIC_DSN___').install();</script>
+  <script src="app.js"></script>
 
 This allows the ability for Raven's integrations to instrument themselves. If
 included before something like Angular, it'd be impossible to use for
@@ -28,7 +28,7 @@ Our CDN distributes builds with and without :doc:`integrations <integrations/ind
 
 .. sourcecode:: html
 
-    <script src="https://cdn.ravenjs.com/###RAVEN_VERSION###/raven.min.js" crossorigin="anonymous"></script>
+  <script src="https://cdn.ravenjs.com/###RAVEN_VERSION###/raven.min.js" crossorigin="anonymous"></script>
 
 This version does not include any plugins. See `ravenjs.com
 <http://ravenjs.com/>`_ for more information about plugins and getting
@@ -45,11 +45,11 @@ add it to ``bower.json``).
 
 .. code-block:: sh
 
-    $ bower install raven-js --save
+  $ bower install raven-js --save
 
 .. code-block:: html
 
-    <script src="/bower_components/raven-js/dist/raven.js"></script>
+  <script src="/bower_components/raven-js/dist/raven.js"></script>
 
 Also note that the file is uncompresed but is ready to pass to any decent
 JavaScript compressor like `UglifyJS
@@ -63,7 +63,7 @@ Raven is also available as an npm package, `raven-js
 
 .. code-block:: sh
 
-    $ npm install raven-js --save
+  $ npm install raven-js --save
 
 .. code-block:: html
 
@@ -96,6 +96,37 @@ To use Raven with ES2015 (ES6) imports:
 	    .config('___PUBLIC_DSN___')
 	    .install();
 
+Async Loading
+~~~~~~~~~~~~~
+
+To load Sentry JS SDK asynchronously, you need to do two things.
+
+Provide global ``SENTRY_SDK`` variable with SDK's URL (for example from our CDN), your DSN and SDK's configuration.
+And place the snippet below as soon as possible in your HTML code. For example:
+
+.. code-block:: html
+
+  <script>
+    window.SENTRY_SDK = {
+      url: 'https://cdn.ravenjs.com/###RAVEN_VERSION###/raven.min.js',
+      dsn: '___PUBLIC_DSN___',
+      options: {
+        release: '1.3.0'
+      }
+    }
+
+    ;(function(a,b,g,e,h){var k=a.SENTRY_SDK,f=function(a){f.data.push(a)};f.data=[];var l=a[e];a[e]=function(c,b,e,d,h){f({e:[].slice.call(arguments)});l&&l.apply(a,arguments)};var m=a[h];a[h]=function(c){f({p:c.reason});m&&m.apply(a,arguments)};var n=b.getElementsByTagName(g)[0];b=b.createElement(g);b.src=k.url;b.crossorigin="anonymous";b.addEventListener("load",function(){try{a[e]=l;a[h]=m;var c=f.data,b=a.Raven;b.config(k.dsn,k.options).install();var g=a[e];if(c.length)for(var d=0;d<c.length;d++)c[d].e?g.apply(b.TraceKit,c[d].e):c[d].p&&b.captureException(c[d].p)}catch(p){console.log(p)}});n.parentNode.insertBefore(b,n)})(window,document,"script","onerror","onunhandledrejection");
+  </script>
+
+Or you can place those two things in a separate script tags. This will queue all errors (and promises if the environment supports ``unhandledrejection`` handler) that happened before SDK was loaded and send them once it's configured and installed.
+
+Be aware however, that there are some trade-offs to this solution, as errors might provide less information due to them being "retriggered" instead of being caught from the original source.
+
+NOTE: This won't work when opening ``index.html`` or any other html file from the file system, as it doesn't support anonymous cross-origin scripts.
+The same thing can happen for any cross-origin scripts as well. To read more about it, see `What the heck is "Script error"?<https://blog.sentry.io/2016/05/17/what-is-script-error>`_.
+
+To read un-minified source code for this loader, see `loader.js<https://github.com/getsentry/raven-js/blob/master/src/loader.js>`_
+
 Requirements
 ~~~~~~~~~~~~
 

karma.sauce.config.js

@@ -3,7 +3,7 @@
 
 module.exports = {
   // base path that will be used to resolve all patterns (eg. files, exclude)
-  basePath: '',
+  basePath: '../',
 
   // frameworks to use
   // available frameworks: https://npmjs.org/browse/keyword/karma-adapter
@@ -58,9 +58,12 @@ module.exports = {
     }
   },
 
+  // https://docs.travis-ci.com/user/gui-and-headless-browsers/#Karma-and-Firefox-inactivity-timeouts
+  browserNoActivityTimeout: 30000,
+
   // Continuous Integration mode
   // if true, Karma captures browsers, runs the tests and exits
-  singleRun: false,
+  singleRun: true,
 
   // Concurrency level
   // how many browser should be started simultaneous

karma.unit.config.js

@@ -0,0 +1,10 @@
+var commonSauceConfig = require('./karma.sauce.config');
+var files = require('./karma.integration.config').files;
+
+module.exports = function(config) {
+  var testConfig = Object.assign({}, commonSauceConfig, {
+    logLevel: config.LOG_INFO,
+    files: files.concat(['build/raven.test.js'])
+  });
+  config.set(testConfig);
+};

karma.config.js renamed to karma/karma.config.js

@@ -9,12 +9,13 @@ var testFiles = [
   {pattern: 'test/integration/throw-object.js', included: false},
   {pattern: 'test/integration/example.json', included: false},
   {pattern: 'test/integration/frame.html', included: false},
-  'test/integration/test.js',
-  'test/globals.js',
-  'build/raven.js',
+  {pattern: 'build/raven.js', included: false},
+  'test/integration/test.js'
 ];
 
 module.exports = function(config) {
   var testConfig = Object.assign({}, commonConfig, {files: testFiles});
   config.set(testConfig);
 };
+
+module.exports.files = testFiles;

karma/karma.integration-sauce.config.js

@@ -0,0 +1,10 @@
+var commonSauceConfig = require('./karma.sauce.config');
+var files = require('./karma.loader.config').files;
+
+module.exports = function(config) {
+  var testConfig = Object.assign({}, commonSauceConfig, {
+    logLevel: config.LOG_INFO,
+    files: files
+  });
+  config.set(testConfig);
+};

karma.integration.config.js renamed to karma/karma.integration.config.js

@@ -0,0 +1,15 @@
+var commonConfig = require('./karma.config');
+
+var testFiles = [
+  {pattern: 'node_modules/es6-promise/dist/es6-promise.auto.js', included: false},
+  {pattern: 'test/integration/loader.html', included: false},
+  {pattern: 'build/raven.js', included: false},
+  {pattern: 'src/loader.js', included: false},
+  'test/integration/loader-test.js'
+];
+
+module.exports = function(config) {
+  var testConfig = Object.assign({}, commonConfig, {files: testFiles});
+  config.set(testConfig);
+};
+module.exports.files = testFiles;

karma/karma.loader-sauce.config.js

@@ -0,0 +1,97 @@
+var commonConfig = require('./karma.config');
+
+var customLaunchers = {
+  sl_chrome: {
+    base: 'SauceLabs',
+    browserName: 'chrome',
+    platform: 'Windows 10',
+    version: 'latest'
+  },
+  sl_firefox: {
+    base: 'SauceLabs',
+    browserName: 'firefox',
+    platform: 'Windows 10',
+    version: 'latest'
+  },
+  sl_edge: {
+    base: 'SauceLabs',
+    browserName: 'microsoftedge',
+    version: 'latest',
+    platform: 'Windows 10'
+  },
+  sl_ie_11: {
+    base: 'SauceLabs',
+    browserName: 'internet explorer',
+    platform: 'Windows 7',
+    version: '11'
+  },
+  sl_ie_10: {
+    base: 'SauceLabs',
+    browserName: 'internet explorer',
+    platform: 'Windows 7',
+    version: '10'
+  },
+  sl_safari: {
+    base: 'SauceLabs',
+    browserName: 'safari',
+    platform: 'OS X 10.12',
+    version: '11.0'
+  },
+  sl_ios: {
+    base: 'SauceLabs',
+    browserName: 'iphone',
+    platform: 'OS X 10.12',
+    version: '11.0'
+  },
+  sl_android_7: {
+    base: 'SauceLabs',
+    browserName: 'Chrome',
+    platform: 'Android',
+    version: '7.1',
+    device: 'Android GoogleAPI Emulator'
+  },
+  sl_android_6: {
+    base: 'SauceLabs',
+    browserName: 'Chrome',
+    platform: 'Android',
+    version: '6.0',
+    device: 'Android Emulator'
+  },
+  sl_android_5: {
+    base: 'SauceLabs',
+    browserName: 'android',
+    platform: 'Linux',
+    version: '5.1'
+  },
+  sl_android_4: {
+    base: 'SauceLabs',
+    browserName: 'android',
+    platform: 'Linux',
+    version: '4.4'
+  }
+};
+
+module.exports = Object.assign({}, commonConfig, {
+  customLaunchers: customLaunchers,
+  browsers: Object.keys(customLaunchers),
+  reporters: ['failed', 'saucelabs'],
+  singleRun: true,
+  plugins: commonConfig.plugins.concat(['karma-sauce-launcher']),
+  build: process.env.TRAVIS_BUILD_NUMBER,
+  // SauceLabs allows for 2 tunnels only, therefore some browsers will have to wait
+  // rather long time. Plus mobile emulators tend to require a lot of time to start up.
+  // 10 minutes should be more than enough to run all of them.
+  browserNoActivityTimeout: 600000,
+  captureTimeout: 600000,
+  sauceLabs: {
+    startConnect: false,
+    // Just something "random" so we don't have to provide additional ENV var when running locally
+    tunnelIdentifier: process.env.TRAVIS_JOB_NUMBER || Math.ceil(Math.random() * 1337),
+    recordScreenshots: false,
+    recordVideo: false,
+    testName:
+      'Raven.js' +
+      (process.env.TRAVIS_JOB_NUMBER ? ' #' + process.env.TRAVIS_JOB_NUMBER : ''),
+    public: 'public'
+  }
+});