feat(config): allow onComplete to return a promise

Closes #1944

Author: sjelin

docs/referenceConf.js

@@ -248,6 +248,8 @@ exports.config = {
   },
 
   // A callback function called once tests are finished.
+  // onComplete can optionally return a promise, which Protractor will wait for
+  // before shutting down webdriver.
   onComplete: function() {
     // At this point, tests will be done but global objects will still be
     // available.

lib/frameworks/README.md

@@ -28,6 +28,8 @@ Requirements
  - `runner.runTestPreparer` must be called before any tests are run.
 
  - `runner.getConfig().onComplete` must be called when tests are finished.
+   It might return a promise, in which case `exports.run`'s promise should not
+   resolve until after `onComplete`'s promise resolves.
 
  - The returned promise must be resolved when tests are finished and it should return a results object. This object must have a `failedCount` property and optionally a `specResults`
  object of the following structure:

lib/frameworks/jasmine.js

@@ -96,12 +96,15 @@ exports.run = function(runner, specs) {
 
       jrunner.onComplete(function(passed) {
         try {
+          var completed = q();
           if (originalOnComplete) {
-            originalOnComplete(passed);
+            completed = q(originalOnComplete(passed));
           }
-          resolve({
-            failedCount: reporter.failedCount,
-            specResults: reporter.testResult
+          completed.then(function() {
+            resolve({
+              failedCount: reporter.failedCount,
+              specResults: reporter.testResult
+            });
           });
         } catch (err) {
           reject(err);

lib/frameworks/mocha.js

@@ -52,12 +52,15 @@ exports.run = function(runner, specs) {
 
     var mochaRunner = mocha.run(function(failures) {
       try {
+        var completed = q();
         if (runner.getConfig().onComplete) {
-          runner.getConfig().onComplete();
+          completed = q(runner.getConfig().onComplete());
         }
-        deferred.resolve({
-          failedCount: failures,
-          specResults: testResult
+        completed.then(function() {
+          deferred.resolve({
+            failedCount: failures,
+            specResults: testResult
+          });
         });
       } catch (err) {
         deferred.reject(err);