feat(config): Support setting SELENIUM_PROMISE_MANAGER flag via the…

… config (#4023)

Closes #3691

.gitignore

@@ -13,6 +13,7 @@ selenium/
 # Build artifacts
 
 built/
+spec/built/
 node_modules/
 website/bower_components/
 website/build/

.jshintignore

@@ -0,0 +1 @@
+./spec/built/*

gulpfile.js

@@ -60,7 +60,7 @@ gulp.task('checkVersion', function(done) {
 });
 
 gulp.task('built:copy', function(done) {
- return gulp.src(['lib/**/*.js','lib/index.d.ts'])
+ return gulp.src(['lib/**/*.js'])
  .pipe(gulp.dest('built/'));
  done();
 });
@@ -94,14 +94,17 @@ gulp.task('tsc', function(done) {
  runSpawn(done, 'node', ['node_modules/typescript/bin/tsc']);
 });
 
+gulp.task('tsc:spec', function(done) {
+ runSpawn(done, 'node', ['node_modules/typescript/bin/tsc', '-p', 'ts_spec_config.json']);
+});
+
 gulp.task('prepublish', function(done) {
- runSequence('checkVersion', 'jshint', 'tsc',
- 'built:copy', done);
+ runSequence('checkVersion', 'jshint', 'tsc', 'built:copy', 'tsc:spec', done);
 });
 
 gulp.task('pretest', function(done) {
  runSequence('checkVersion',
- ['webdriver:update', 'jshint', 'tslint', 'format'], 'tsc', 'built:copy', done);
+ ['webdriver:update', 'jshint', 'tslint', 'format'], 'tsc', 'built:copy', 'tsc:spec', done);
 });
 
 gulp.task('default',['prepublish']);

lib/config.ts

@@ -601,6 +601,29 @@ export interface Config {
  */
  disableChecks?: boolean;
 
+ /**
+ * Enable/disable the WebDriver Control Flow.
+ *
+ * WebDriverJS (and by extention, Protractor) uses a Control Flow to manage the order in which
+ * commands are executed and promises are resolved (see docs/control-flow.md for details).
+ * However, as syntax like `async`/`await` are being introduced, WebDriverJS has decided to
+ * deprecate the control flow, and have users manage the asynchronous activity themselves
+ * (details here: https:/SeleniumHQ/selenium/issues/2969).
+ *
+ * At the moment, the WebDriver Control Flow is still enabled by default. You can disable it by
+ * setting the environment variable `SELENIUM_PROMISE_MANAGER` to `0`. In a webdriver release in
+ * Q4 2017, the Control Flow will be disabled by default, but you will be able to re-enable it by
+ * setting `SELENIUM_PROMISE_MANAGER` to `1`. At a later point, the control flow will be removed
+ * for good.
+ *
+ * If you don't like managing environment variables, you can set this option in your config file,
+ * and Protractor will handle enabling/disabling the control flow for you. Setting this option
+ * is higher priority than the `SELENIUM_PROMISE_MANAGER` environment variable.
+ *
+ * @type {boolean=}
+ */
+ SELENIUM_PROMISE_MANAGER?: boolean;
+
  seleniumArgs?: any[];
  jvmArgs?: string[];
  configDir?: string;

lib/runner.ts

@@ -343,6 +343,10 @@ export class Runner extends EventEmitter {
  throw new Error('Spec patterns did not match any files.');
  }
 
+ if (this.config_.SELENIUM_PROMISE_MANAGER != null) {
+ (wdpromise as any).USE_PROMISE_MANAGER = this.config_.SELENIUM_PROMISE_MANAGER;
+ }
+
  // 0) Wait for debugger
  return q(this.ready_)
  .then(() => {

package.json

@@ -32,6 +32,7 @@
  "@types/chalk": "^0.4.28",
  "@types/glob": "^5.0.29",
  "@types/jasmine": "^2.5.38",
+ "@types/jasminewd2": "^2.0.0",
  "@types/minimatch": "^2.0.28",
  "@types/minimist": "^1.1.28",
  "@types/optimist": "^0.0.29",

scripts/test.js

@@ -38,6 +38,7 @@ var passingTests = [
  'node built/cli.js spec/noGlobalsConf.js',
  'node built/cli.js spec/angular2Conf.js',
  'node built/cli.js spec/hybridConf.js',
+ 'node built/cli.js spec/built/noCFSmokeConf.js',
  'node scripts/driverProviderAttachSession.js',
  'node scripts/errorTest.js',
  // Interactive Element Explorer tasks

spec/ts/noCF/smoke_spec.ts

@@ -0,0 +1,157 @@
+// Based off of spec/basic/elements_spec.js
+import {promise as ppromise, browser, element, by, By, $, $$, ExpectedConditions, ElementFinder} from '../../..';
+
+describe('ElementFinder', function() {
+ it('should return the same result as browser.findElement', async function() {
+ await browser.get('index.html#/form');
+ const nameByElement = element(by.binding('username'));
+
+ await expect(nameByElement.getText()).toEqual(
+ browser.findElement(by.binding('username')).getText());
+ });
+
+ it('should wait to grab the WebElement until a method is called', async function() {
+ // These should throw no error before a page is loaded.
+ const usernameInput = element(by.model('username'));
+ const name = element(by.binding('username'));
+
+ await browser.get('index.html#/form');
+
+ await expect(name.getText()).toEqual('Anon');
+
+ await usernameInput.clear();
+ await usernameInput.sendKeys('Jane');
+ await expect(name.getText()).toEqual('Jane');
+ });
+
+ it('should chain element actions', async function() {
+ await browser.get('index.html#/form');
+
+ const usernameInput = element(by.model('username'));
+ const name = element(by.binding('username'));
+
+ await expect(name.getText()).toEqual('Anon');
+
+ await ((usernameInput.clear() as any) as ElementFinder).sendKeys('Jane');
+ await expect(name.getText()).toEqual('Jane');
+ });
+
+ it('chained call should wait to grab the WebElement until a method is called',
+ async function() {
+ // These should throw no error before a page is loaded.
+ const reused = element(by.id('baz')).
+ element(by.binding('item.reusedBinding'));
+
+ await browser.get('index.html#/conflict');
+
+ await expect(reused.getText()).toEqual('Inner: inner');
+ await expect(reused.isPresent()).toBe(true);
+ });
+
+ it('should differentiate elements with the same binding by chaining',
+ async function() {
+ await browser.get('index.html#/conflict');
+
+ const outerReused = element(by.binding('item.reusedBinding'));
+ const innerReused =
+ element(by.id('baz')).element(by.binding('item.reusedBinding'));
+
+ await expect(outerReused.getText()).toEqual('Outer: outer');
+ await expect(innerReused.getText()).toEqual('Inner: inner');
+ });
+
+ it('should chain deeper than 2', async function() {
+ // These should throw no error before a page is loaded.
+ const reused = element(by.css('body')).element(by.id('baz')).
+ element(by.binding('item.reusedBinding'));
+
+ await browser.get('index.html#/conflict');
+
+ await expect(reused.getText()).toEqual('Inner: inner');
+ });
+
+ it('should allow handling errors', async function() {
+ await browser.get('index.html#/form');
+ try {
+ await $('.nopenopenope').getText();
+
+ // The above line should have throw an error. Fail.
+ await expect(true).toEqual(false);
+ } catch (e) {
+ await expect(true).toEqual(true);
+ }
+ });
+
+ it('should allow handling chained errors', async function() {
+ await browser.get('index.html#/form');
+ try {
+ await $('.nopenopenope').$('furthernope').getText();
+
+ // The above line should have throw an error. Fail.
+ await expect(true).toEqual(false);
+ } catch (e) {
+ await expect(true).toEqual(true);
+ }
+ });
+
+ it('should keep a reference to the original locator', async function() {
+ await browser.get('index.html#/form');
+
+ const byCss = by.css('body');
+ const byBinding = by.binding('greet');
+
+ await expect(element(byCss).locator()).toEqual(byCss);
+ await expect(element(byBinding).locator()).toEqual(byBinding);
+ });
+
+ it('should propagate exceptions', async function() {
+ await browser.get('index.html#/form');
+
+ const invalidElement = element(by.binding('INVALID'));
+ const successful = invalidElement.getText().then(function() {
+ return true;
+ } as any as (() => ppromise.Promise<void>), function() {
+ return false;
+ } as any as (() => ppromise.Promise<void>));
+ await expect(successful).toEqual(false);
+ });
+
+ it('should be returned from a helper without infinite loops', async function() {
+ await browser.get('index.html#/form');
+ const helperPromise = ppromise.when(true).then(function() {
+ return element(by.binding('greeting'));
+ });
+
+ await helperPromise.then(async function(finalResult: ElementFinder) {
+ await expect(finalResult.getText()).toEqual('Hiya');
+ } as any as (() => ppromise.Promise<void>));
+ });
+
+ it('should be usable in WebDriver functions', async function() {
+ await browser.get('index.html#/form');
+ const greeting = element(by.binding('greeting'));
+ await browser.executeScript('arguments[0].scrollIntoView', greeting);
+ });
+
+ it('should allow null as success handler', async function() {
+ await browser.get('index.html#/form');
+
+ const name = element(by.binding('username'));
+
+ await expect(name.getText()).toEqual('Anon');
+ await expect(
+ name.getText().then(null, function() {})
+ ).toEqual('Anon');
+
+ });
+
+ it('should check equality correctly', async function() {
+ await browser.get('index.html#/form');
+
+ const usernameInput = element(by.model('username'));
+ const name = element(by.binding('username'));
+
+ await expect(usernameInput.equals(usernameInput)).toEqual(true);
+ await expect(usernameInput.equals(name)).toEqual(false);
+ });
+});

spec/ts/noCFSmokeConf.ts

@@ -0,0 +1,18 @@
+import {Config} from '../..';
+const env = require('../environment.js');
+
+export let config: Config = {
+ seleniumAddress: env.seleniumAddress,
+
+ framework: 'jasmine',
+
+ specs: [
+ 'noCF/smoke_spec.js'
+ ],
+
+ capabilities: env.capabilities,
+
+ baseUrl: env.baseUrl + '/ng1/',
+
+ SELENIUM_PROMISE_MANAGER: false
+};

ts_spec_config.json

@@ -0,0 +1,21 @@
+{
+ "compilerOptions": {
+ "target": "es6",
+ "module": "commonjs",
+ "moduleResolution": "node",
+ "sourceMap": true,
+ "declaration": true,
+ "removeComments": false,
+ "noImplicitAny": true,
+ "outDir": "spec/built",
+ "types": [
+ "jasmine", "jasminewd2", "node",
+ "chalk", "glob", "minimatch",
+ "minimist", "optimist", "q",
+ "selenium-webdriver"
+ ]
+ },
+ "include": [
+ "spec/ts"
+ ]
+}

tsconfig.json

@@ -9,7 +9,7 @@
  "noImplicitAny": true,
  "outDir": "built/",
  "types": [
- "jasmine", "node",
+ "jasmine", "jasminewd2", "node",
  "chalk", "glob", "minimatch",
  "minimist", "optimist", "q",
  "selenium-webdriver"