build(browserstack): add a Gulp task to use Browser Stack locally

Closes #5116

DEVELOPER.md

@@ -189,6 +189,27 @@ tests respectively.
 **Note**: **watch mode** needs symlinks to work, so if you're using windows, ensure you have the
 rights to built them in your operating system.
 
+### Unit tests with Sauce Labs or Browser Stack
+
+First, in a terminal, create a tunnel with [Sauce Connect](https://docs.saucelabs.com/reference/sauce-connect/) or [Browser Stack Local](https://www.browserstack.com/local-testing#command-line), and valid credentials.  
+
+Then, in another terminal:
+ - Define the credentials as environment variables, e.g.:
+```
+export SAUCE_USERNAME='my_user'; export SAUCE_ACCESS_KEY='my_key';
+export BROWSER_STACK_USERNAME='my_user'; export BROWSER_STACK_ACCESS_KEY='my_key';
+```
+ - Then run `gulp test.unit.js.(saucelabs|browserstack) --browsers=option1,option2,..,optionN`  
+The options are any mix of browsers and aliases which are defined in the [browser-providers.conf.js](https://github.com/angular/angular/blob/master/browser-providers.conf.js) file.  
+They are case insensitive, and the `SL_` or `BS_` prefix must not be added for browsers.
+
+Some examples of commands:
+```
+gulp test.unit.js.saucelabs --browsers=Safari8,ie11  //run in Sauce Labs with Safari 8 and IE11
+gulp test.unit.js.browserstack --browsers=Safari,IE  //run in Browser Stack with Safari 7, Safari 8, Safari 9, IE 9, IE 10 and IE 11
+gulp test.unit.js.saucelabs --browsers=IOS,safari8,android5.1  //run in Sauce Labs with iOS 7, iOS 8, iOs 9, Safari 8 and Android 5.1
+```
+
 ### E2E tests
 
 1. `$(npm bin)/gulp build.js.cjs` (builds benchpress and tests into `dist/js/cjs` folder).

gulpfile.js

@@ -454,8 +454,8 @@ gulp.task('test.all.dart', shell.task(['./scripts/ci/test_dart.sh']));
 // karma tests
 //     These tests run in the browser and are allowed to access
 //     HTML DOM APIs.
-function getBrowsersFromCLI() {
+function getBrowsersFromCLI(provider) {
-  var isSauce = false;
+  var isProvider = false;
   var args = minimist(process.argv.slice(2));
   var rawInput = args.browsers ? args.browsers : 'DartiumWithWebPlatform';
   var inputList = rawInput.replace(' ', '').split(',');
@@ -467,21 +467,24 @@ function getBrowsersFromCLI() {
       // In case of non-sauce browsers, or browsers defined in karma-chrome-launcher (Chrome, ChromeCanary and Dartium):
       // overrides everything, ignoring other options
       outputList = [input];
-      isSauce = false;
+      isProvider = false;
       break;
-    } else if (browserProvidersConf.customLaunchers.hasOwnProperty("SL_" + input.toUpperCase())) {
+    } else if (provider && browserProvidersConf.customLaunchers.hasOwnProperty(provider + "_" + input.toUpperCase())) {
-      isSauce = true;
+      isProvider = true;
-      outputList.push("SL_" + input.toUpperCase());
+      outputList.push(provider + "_" + input.toUpperCase());
-    } else if (browserProvidersConf.sauceAliases.hasOwnProperty(input.toUpperCase())) {
+    } else if (provider && provider == 'SL' && browserProvidersConf.sauceAliases.hasOwnProperty(input.toUpperCase())) {
-      outputList = outputList.concat(browserProvidersConf.sauceAliases[input]);
+      outputList = outputList.concat(browserProvidersConf.sauceAliases[input.toUpperCase()]);
-      isSauce = true;
+      isProvider = true;
+    } else if (provider && provider == 'BS' && browserProvidersConf.browserstackAliases.hasOwnProperty(input.toUpperCase())) {
+      outputList = outputList.concat(browserProvidersConf.browserstackAliases[input.toUpperCase()]);
+      isProvider = true;
     } else {
       throw new Error('ERROR: unknown browser found in getBrowsersFromCLI()');
     }
   }
   return {
     browsersToRun: outputList.filter(function(item, pos, self) {return self.indexOf(item) == pos;}),
-    isSauce: isSauce
+    isProvider: isProvider
   };
 }
 
@@ -502,21 +505,34 @@ gulp.task('watch.js.dev', ['build.js.dev'], function (done) {
 });
 
 gulp.task('test.unit.js.sauce', ['build.js.dev'], function (done) {
-  var browserConf = getBrowsersFromCLI();
+  var browserConf = getBrowsersFromCLI('SL');
-  if (browserConf.isSauce) {
+  if (browserConf.isProvider) {
-    new karma.Server({
+    launchKarmaWithExternalBrowsers(['dots'], browserConf.browsersToRun, done);
-        configFile: __dirname + '/karma-js.conf.js',
-        singleRun: true,
-        browserNoActivityTimeout: 240000,
-        captureTimeout: 120000,
-        reporters: ['dots'],
-        browsers: browserConf.browsersToRun},
-      function(err) {done(); process.exit(err ? 1 : 0);}).start();
   } else {
     throw new Error('ERROR: no Saucelabs browsers provided, add them with the --browsers option');
   }
 });
 
+gulp.task('test.unit.js.browserstack', ['build.js.dev'], function (done) {
+  var browserConf = getBrowsersFromCLI('BS');
+  if (browserConf.isProvider) {
+    launchKarmaWithExternalBrowsers(['dots'], browserConf.browsersToRun, done);
+  } else {
+    throw new Error('ERROR: no Browserstack browsers provided, add them with the --browsers option');
+  }
+});
+
+function launchKarmaWithExternalBrowsers(reporters, browsers, done) {
+  new karma.Server({
+    configFile: __dirname + '/karma-js.conf.js',
+    singleRun: true,
+    browserNoActivityTimeout: 240000,
+    captureTimeout: 120000,
+    reporters: reporters,
+    browsers: browsers},
+  function(err) {done(); process.exit(err ? 1 : 0);}).start();
+}
+
 gulp.task('!test.unit.js/karma-server', function(done) {
   var watchStarted = false;
   var server = new karma.Server({configFile: __dirname + '/karma-js.conf.js', reporters: 'dots'});
@@ -655,29 +671,11 @@ gulp.task('test.unit.js/ci', function (done) {
 });
 
 gulp.task('test.unit.js.sauce/ci', function (done) {
-  new karma.Server({
+  launchKarmaWithExternalBrowsers(['dots', 'saucelabs'], browserProvidersConf.sauceAliases.CI, done);
-        configFile: __dirname + '/karma-js.conf.js',
-        singleRun: true,
-        browserNoActivityTimeout: 240000,
-        captureTimeout: 120000,
-        reporters: ['dots', 'saucelabs'],
-        browsers: browserProvidersConf.sauceAliases.CI
-      },
-      function(err) {done(); process.exit(err ? 1 : 0);}
-  ).start();
 });
 
 gulp.task('test.unit.js.browserstack/ci', function (done) {
-  new karma.Server({
+  launchKarmaWithExternalBrowsers(['dots'], browserProvidersConf.browserstackAliases.CI, done);
-      configFile: __dirname + '/karma-js.conf.js',
-      singleRun: true,
-      browserNoActivityTimeout: 240000,
-      captureTimeout: 120000,
-      reporters: ['dots'],
-      browsers: browserProvidersConf.browserstackAliases.CI
-    },
-    function(err) {done(); process.exit(err ? 1 : 0);}
-  ).start();
 });
 
 gulp.task('test.unit.dart/ci', function (done) {