feat(runner): allow onPrepare functions to return a promise

If onPrepare is a function which returns a promise (or a file which exports
a promise), the test runner will now wait for that promise to be fulfilled
before starting tests.

lib/frameworks/cucumber.js

@@ -52,10 +52,7 @@ exports.run = function(runner, specs, done) {
   }
   global.cucumber = Cucumber.Cli(execOptions);
 
-  runner.controlFlow().execute(function() {
-    runner.runTestPreparers();
-  }, 'run test preparers').then(function() {
-
+  runner.runTestPreparers().then(function() {
     global.cucumber.run(function(succeeded) {
       if (runner.getConfig().onComplete) {
         runner.getConfig().onComplete();

lib/frameworks/jasmine.js

@@ -35,9 +35,7 @@ exports.run = function(runner, specs, done) {
   // get to complete first.
   jasmine.getEnv().addReporter(new RunnerReporter(runner));
 
-  runner.controlFlow().execute(function() {
-    runner.runTestPreparers();
-  }, 'run test preparers').then(function() {
+  runner.runTestPreparers().then(function() {
     var jasmineNodeOpts = runner.getConfig().jasmineNodeOpts;
     var originalOnComplete = runner.getConfig().onComplete;
     jasmineNodeOpts.onComplete = function(jasmineRunner, log) {

lib/frameworks/mocha.js

@@ -43,9 +43,7 @@ exports.run = function(runner, specs, done) {
 
   mocha.loadFiles();
 
-  runner.controlFlow().execute(function() {
-    runner.runTestPreparers();
-  }, 'run test preparers').then(function() {
+  runner.runTestPreparers().then(function() {
 
     specs.forEach(function(file) {
       mocha.addFile(file);

lib/runner.js

@@ -54,22 +54,30 @@ util.inherits(Runner, EventEmitter);
  * @private
  * @param {Array} source The Array that we'll be iterating through
  *    as we evaluate whether to require or execute each item.
+ * @return {q.Promise} A promise that will resolve when the test preparers
+ *     are finished.
  */
 Runner.prototype.runFilenamesOrFns_ = function(source) {
   var filenameOrFn;
+  var promises = [];
+  var returned;
   for (var i = 0; i < source.length; i++) {
     filenameOrFn = source[i];
     if (filenameOrFn) {
       if (typeof filenameOrFn === 'function') {
-        filenameOrFn();
+        returned = filenameOrFn();
       } else if (typeof filenameOrFn === 'string') {
-        require(path.resolve(this.config_.configDir, filenameOrFn));
+        returned = require(path.resolve(this.config_.configDir, filenameOrFn));
       } else {
         // TODO - this is not generic.
         throw 'config.onPrepare must be a string or function';
       }
+      if (q.isPromiseAlike(returned)) {
+        promises.push(returned);
+      }
     }
   }
+  return q.all(promises);
 };
 
 
@@ -86,9 +94,11 @@ Runner.prototype.registerTestPreparer = function(filenameOrFn) {
 /**
  * Executor of testPreparers
  * @public
+ * @return {q.Promise} A promise that will resolve when the test preparers
+ *     are finished.
  */
 Runner.prototype.runTestPreparers = function() {
-  this.runFilenamesOrFns_(this.preparers_);
+  return this.runFilenamesOrFns_(this.preparers_);
 };
 
 

scripts/test.js

@@ -9,6 +9,8 @@ var scripts = [
   'node lib/cli.js spec/altRootConf.js',
   'node lib/cli.js spec/onPrepareConf.js',
   'node lib/cli.js spec/onPrepareFileConf.js',
+  'node lib/cli.js spec/onPreparePromiseConf.js',
+  'node lib/cli.js spec/onPreparePromiseFileConf.js',
   'node lib/cli.js spec/mochaConf.js',
   'node lib/cli.js spec/cucumberConf.js',
   'node lib/cli.js spec/withLoginConf.js',

spec/onPrepare/asyncstartup.js

@@ -0,0 +1,5 @@
+var q = require('q');
+
+module.exports = q.fcall(function() {
+  browser.params.password = '12345';
+}).delay(1000);

spec/onPreparePromiseConf.js

@@ -0,0 +1,23 @@
+// Configuration using a function in onPrepare to set a parameter before
+// testing.
+var env = require('./environment.js');
+var q = require('q');
+
+// The main suite of Protractor tests.
+exports.config = {
+  seleniumAddress: env.seleniumAddress,
+
+  specs: [
+    'onPrepare/*_spec.js'
+  ],
+
+  capabilities: env.capabilities,
+
+  baseUrl: env.baseUrl,
+
+  onPrepare: function() {
+    return q.fcall(function() {
+      browser.params.password = '12345';
+    }).delay(1000);
+  }
+};

spec/onPreparePromiseFileConf.js

@@ -0,0 +1,18 @@
+var env = require('./environment.js');
+
+// Configuration using a string in onPrepare to load a file with code to
+// execute once before tests.
+exports.config = {
+  seleniumAddress: env.seleniumAddress,
+
+  // Spec patterns are relative to this directory.
+  specs: [
+    'onPrepare/*_spec.js'
+  ],
+
+  capabilities: env.capabilities,
+
+  baseUrl: env.baseUrl,
+
+  onPrepare: 'onPrepare/asyncstartup.js'
+};