feat(plugins): support onPrepare in plugins (#3483)

Author: sjelin

docs/plugins.md

@@ -94,6 +94,22 @@ Plugins are node modules which export an object with the following API:
  */
 exports.setup = function() {};
 
+/**
+ * This is called before the test have been run but after the test framework has
+ * been set up.  Analogous to a config file's `onPreare`.
+ *
+ * Very similar to using `setup`, but allows you to access framework-specific
+ * variables/funtions (e.g. `jasmine.getEnv().addReporter()`)
+ *
+ * @throws {*} If this function throws an error, a failed assertion is added to
+ *     the test results.
+ *
+ * @return {Q.Promise=} Can return a promise, in which case protractor will wait
+ *     for the promise to resolve before continuing.  If the promise is
+ *     rejected, a failed assertion is added to the test results.
+ */
+exports.onPrepare = function() {};
+
 /**
  * This is called after the tests have been run, but before the WebDriver
  * session has been terminated.

lib/plugins.ts

@@ -34,6 +34,22 @@ export interface ProtractorPlugin {
    */
   setup?: () => Q.Promise<any>;
 
+  /**
+   * This is called before the test have been run but after the test framework has
+   * been set up.  Analogous to a config file's `onPreare`.
+   *
+   * Very similar to using `setup`, but allows you to access framework-specific
+   * variables/funtions (e.g. `jasmine.getEnv().addReporter()`)
+   *
+   * @throws {*} If this function throws an error, a failed assertion is added to
+   *     the test results.
+   *
+   * @return {Q.Promise=} Can return a promise, in which case protractor will wait
+   *     for the promise to resolve before continuing.  If the promise is
+   *     rejected, a failed assertion is added to the test results.
+   */
+  onPrepare?: () => Q.Promise<any>;
+
   /**
    * This is called after the tests have been run, but before the WebDriver
    * session has been terminated.
@@ -396,6 +412,7 @@ export class Plugins {
    * @see docs/plugins.md#writing-plugins for information on these functions
    */
   setup: Function = pluginFunFactory('setup', PromiseType.Q);
+  onPrepare: Function = pluginFunFactory('onPrepare', PromiseType.Q);
   teardown: Function = pluginFunFactory('teardown', PromiseType.Q);
   postResults: Function = pluginFunFactory('postResults', PromiseType.Q);
   postTest: Function = pluginFunFactory('postTest', PromiseType.Q);

lib/runner.ts

@@ -31,6 +31,7 @@ export class Runner extends EventEmitter {
   preparer_: any;
   driverprovider_: DriverProvider;
   o: any;
+  plugins_: Plugins;
 
   constructor(config: Config) {
     super();
@@ -76,7 +77,9 @@ export class Runner extends EventEmitter {
    *     are finished.
    */
   runTestPreparer(): q.Promise<any> {
-    return helper.runFilenameOrFn_(this.config_.configDir, this.preparer_);
+    return this.plugins_.onPrepare().then(() => {
+      return helper.runFilenameOrFn_(this.config_.configDir, this.preparer_);
+    });
   }
 
   /**
@@ -268,7 +271,7 @@ export class Runner extends EventEmitter {
    */
   run(): q.Promise<any> {
     let testPassed: boolean;
-    let plugins = new Plugins(this.config_);
+    let plugins = this.plugins_ = new Plugins(this.config_);
     let pluginPostTestPromises: any;
     let browser_: any;
     let results: any;

spec/plugins/plugins/basic_plugin.js

@@ -1,5 +1,8 @@
 module.exports = {
   setup: function() {
-    protractor.__BASIC_PLUGIN_RAN = true;
+    protractor.__BASIC_PLUGIN_RAN_SETUP = true;
+  },
+  onPrepare: function() {
+    protractor.__BASIC_PLUGIN_RAN_ON_PREPARE = true;
   }
 };

spec/plugins/specs/smoke_spec.js

@@ -1,5 +1,6 @@
 describe('check if plugin setup ran', function() {
-  it('should have set protractor.__BASIC_PLUGIN_RAN', function() {
-    expect(protractor.__BASIC_PLUGIN_RAN).toBe(true);
+  it('should have set protractor.__BASIC_PLUGIN_RAN_*', function() {
+    expect(protractor.__BASIC_PLUGIN_RAN_SETUP).toBe(true);
+    expect(protractor.__BASIC_PLUGIN_RAN_ON_PREPARE).toBe(true);
   });
 });