feat(frameworks): add support for custom frameworks

Usage:
```js
exports.config = {
  framework: 'custom',
  frameworkPath: '/path/to/your/framework/index.js'
}
```

Author: elgalu

docs/referenceConf.js

@@ -244,7 +244,15 @@ exports.config = {
   // ----- The test framework --------------------------------------------------
   // ---------------------------------------------------------------------------
 
-  // Test framework to use. This may be jasmine, jasmine2, cucumber, or mocha.
+  // Test framework to use. This may be one of:
+  //  jasmine, jasmine2, cucumber, mocha or custom.
+  //
+  // When the framework is set to "custom" you'll need to additionally
+  // set frameworkPath with the path relative to the config file or absolute
+  //  framework: 'custom',
+  //  frameworkPath: './frameworks/my_custom_jasmine.js',
+  // See github.com/angular/protractor/blob/master/lib/frameworks/README.md
+  // to comply with the interface details of your custom implementation.
   //
   // Jasmine is fully supported as a test and assertion framework.
   // Mocha and Cucumber have limited beta support. You will need to include your

lib/configParser.js

@@ -146,7 +146,8 @@ ConfigParser.getSpecs = function(config) {
 ConfigParser.prototype.addConfig_ = function(additionalConfig, relativeTo) {
   // All filepaths should be kept relative to the current config location.
   // This will not affect absolute paths.
-  ['seleniumServerJar', 'chromeDriver', 'onPrepare', 'firefoxPath'].
+  ['seleniumServerJar', 'chromeDriver', 'onPrepare', 'firefoxPath', 
+   'frameworkPath'].
       forEach(function(name) {
         if (additionalConfig[name] &&
             typeof additionalConfig[name] === 'string') {

lib/frameworks/README.md

@@ -36,3 +36,24 @@ Requirements
      duration: integer
    }]
  ```
+
+Custom Frameworks
+-----------------
+
+If you have created/adapted a custom framework and want it added to 
+Protractor core please send a PR so it can evaluated for addition as an 
+official supported framework. In the meantime you can instruct Protractor
+to use your own framework via the config file:
+
+```js
+exports.config = {
+  // set to "custom" instead of jasmine/jasmine2/mocha/cucumber.
+  framework: 'custom',
+  // path relative to the current config file
+  frameworkPath: './frameworks/my_custom_jasmine.js',
+};
+```
+
+More on this at [referenceConf](../../docs/referenceConf.js) "The test framework" section.
+
+**Disclaimer**: current framework interface can change without a major version bump.

lib/runner.js

@@ -286,6 +286,12 @@ Runner.prototype.run = function() {
     } else if (self.config_.framework === 'explorer') {
       // Private framework. Do not use.
       frameworkPath = './frameworks/explorer.js';
+    } else if (self.config_.framework === 'custom') {
+      if (!self.config_.frameworkPath) {
+        throw new Error('When config.framework is custom, ' +
+          'config.frameworkPath is required.');
+      }
+      frameworkPath = self.config_.frameworkPath;
     } else {
       throw new Error('config.framework (' + self.config_.framework +
           ') is not a valid framework.');

scripts/test.js

@@ -27,6 +27,7 @@ var passingTests = [
   'node lib/cli.js spec/restartBrowserBetweenTestsConf.js',
   'node lib/cli.js spec/getCapabilitiesConf.js',
   'node lib/cli.js spec/controlLockConf.js',
+  'node lib/cli.js spec/customFramework.js',
   'node node_modules/.bin/jasmine JASMINE_CONFIG_PATH=scripts/unit_test.json'
 ];
 

spec/custom/framework.js

@@ -0,0 +1,9 @@
+/**
+ * Jasmine framework dummy alias to prove Protractor supports 
+ * external custom frameworks.
+ * 
+ * @param {Runner} runner The current Protractor Runner.
+ * @param {Array} specs Array of Directory Path Strings.
+ * @return {q.Promise} Promise resolved with the test results
+ */
+exports.run = require('../../lib/frameworks/jasmine.js').run;

spec/custom/smoke_spec.js

@@ -0,0 +1,5 @@
+describe('smoke jasmine tests', function() {
+  it('should do some dummy test', function() {
+    expect(1).toBe(1);
+  });
+});

spec/customFramework.js

@@ -0,0 +1,16 @@
+var env = require('./environment.js');
+
+exports.config = {
+  seleniumAddress: env.seleniumAddress,
+
+  framework: 'custom',
+  frameworkPath: './custom/framework.js',
+
+  specs: [
+    'custom/smoke_spec.js'
+  ],
+
+  capabilities: env.capabilities,
+
+  baseUrl: env.baseUrl,
+};

spec/unit/runner_test.js

@@ -46,4 +46,17 @@ describe('the Protractor runner', function() {
       runner.run();
     }).toThrow();
   });
+
+  it('should fail when no custom framework is defined', function(done) {
+    var config = {
+      mockSelenium: true,
+      specs: ['*.js'],
+      framework: 'custom'
+    };
+
+    var runner = new Runner(config);
+    runner.run().then(function() {
+      done.fail('expected error when no custom framework is defined');
+    }, done);
+  });
 });