selenium-webdriver 2.47.0 → 2.52.0

package/testing/assert.js

@@ -32,30 +32,347 @@
  *     assert(driver.getTitle()).equalTo('Google');
  */
 
-var base = require('../_base'),
-    assert = base.require('webdriver.testing.assert');
+'use strict';
 
+const assert = require('assert');
 
-// PUBLIC API
+function trueType(v) {
+  if (v === null) {
+    return 'null';
+  }
+
+  let type = typeof v;
+  if (type === 'object') {
+    if (Array.isArray(v)) {
+      type = 'array';
+    }
+  }
+  return type;
+}
+
+
+function checkType(v, want) {
+  let got = trueType(v);
+  if (got !== want) {
+    throw new TypeError('require ' + want + ', but got ' + got);
+  }
+  return v;
+}
+
+const checkNumber = v => checkType(v, 'number');
+const checkFunction = v => checkType(v, 'function');
+const checkString = v => checkType(v, 'string');
+
+const isFunction = v => trueType(v) === 'function';
+const isNumber = v => trueType(v) === 'number';
+const isObject = v => trueType(v) === 'object';
+const isString = v => trueType(v) === 'string';
+
+
+function describe(value) {
+  let ret;
+  try {
+    ret = `<${String(value)}>`;
+  } catch (e) {
+    ret = `<toString failed: ${e.message}>`;
+  }
+
+  if (null !== value && void(0) !== value) {
+    ret += ` (${trueType(value)})`;
+  }
+
+  return ret;
+}
+
+
+function evaluate(value, predicate) {
+  if (isObject(value) && isFunction(value.then)) {
+    return value.then(predicate);
+  }
+  predicate(value);
+}
 
 
 /**
- * Creates a new assertion.
- * @param {*} value The value to perform an assertion on.
- * @return {!webdriver.testing.Assertion} The new assertion.
+ * @private
  */
-module.exports = function(value) {
-  return assert(value);
-};
+class Assertion {
+  /**
+   * @param {?} subject The subject of this assertion.
+   * @param {boolean=} opt_invert Whether to invert any assertions performed by
+   *     this instance.
+   */
+  constructor(subject, opt_invert) {
+    /** @private {?} */
+    this.subject_ = subject;
+    /** @private {boolean} */
+    this.invert_ = !!opt_invert;
+  }
+
+  /**
+   * @param {number} expected The minimum permissible value (inclusive).
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  atLeast(expected, opt_message) {
+    checkNumber(expected);
+    return evaluate(this.subject_, function(actual) {
+      if (!isNumber(actual) || actual < expected) {
+        assert.fail(actual, expected, opt_message, '>=');
+      }
+    });
+  }
+
+  /**
+   * @param {number} expected The maximum permissible value (inclusive).
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  atMost(expected, opt_message) {
+    checkNumber(expected);
+    return evaluate(this.subject_, function (actual) {
+      if (!isNumber(actual) || actual > expected) {
+        assert.fail(actual, expected, opt_message, '<=');
+      }
+    });
+  }
+
+  /**
+   * @param {number} expected The maximum permissible value (exclusive).
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  greaterThan(expected, opt_message) {
+    checkNumber(expected);
+    return evaluate(this.subject_, function(actual) {
+      if (!isNumber(actual) || actual <= expected) {
+        assert.fail(actual, expected, opt_message, '>');
+      }
+    });
+  }
+
+  /**
+   * @param {number} expected The minimum permissible value (exclusive).
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  lessThan(expected, opt_message) {
+    checkNumber(expected);
+    return evaluate(this.subject_,  function (actual) {
+      if (!isNumber(actual) || actual >= expected) {
+        assert.fail(actual, expected, opt_message, '<');
+      }
+    });
+  }
+
+  /**
+   * @param {number} expected The desired value.
+   * @param {number} epsilon The maximum distance from the desired value.
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  closeTo(expected, episolon, opt_message) {
+    checkNumber(expected);
+    checkNumber(episolon);
+    return evaluate(this.subject_, function(actual) {
+      checkNumber(actual);
+      if (Math.abs(expected - actual) > episolon) {
+        assert.fail(opt_message || `${actual} === ${expected} (± ${episolon})`);
+      }
+    });
+  }
+
+  /**
+   * @param {function(new: ?)} ctor The exptected type's constructor.
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  instanceOf(ctor, opt_message) {
+    checkFunction(ctor);
+    return evaluate(this.subject_, function(actual) {
+      if (!(actual instanceof ctor)) {
+        assert.fail(
+            opt_message
+                || `${describe(actual)} instanceof ${ctor.name || ctor}`);
+      }
+    });
+  }
+
+  /**
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  isNull(opt_message) {
+    return this.isEqualTo(null);
+  }
+
+  /**
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  isUndefined(opt_message) {
+    return this.isEqualTo(void(0));
+  }
+
+  /**
+   * Ensures the subject of this assertion is either a string or array
+   * containing the given `value`.
+   *
+   * @param {?} value The value expected to be contained within the subject.
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  contains(value, opt_message) {
+    return evaluate(this.subject_, function(actual) {
+      if (actual instanceof Map || actual instanceof Set) {
+        assert.ok(actual.has(value), opt_message || `${actual}.has(${value})`);
+      } else if (Array.isArray(actual) || isString(actual)) {
+        assert.ok(
+            actual.indexOf(value) !== -1,
+            opt_message || `${actual}.indexOf(${value}) !== -1`);
+      } else {
+        assert.fail(
+            `Expected an array, map, set, or string: got ${describe(actual)}`);
+      }
+    });
+  }
+
+  /**
+   * @param {string} str The expected suffix.
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  endsWith(str, opt_message) {
+    checkString(str);
+    return evaluate(this.subject_, function(actual) {
+      if (!isString(actual) || !actual.endsWith(str)) {
+        assert.fail(actual, str, 'ends with');
+      }
+    });
+  }
+
+  /**
+   * @param {string} str The expected prefix.
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  startsWith(str, opt_message) {
+    checkString(str);
+    return evaluate(this.subject_, function(actual) {
+      if (!isString(actual) || !actual.startsWith(str)) {
+        assert.fail(actual, str, 'starts with');
+      }
+    });
+  }
+
+  /**
+   * @param {!RegExp} regex The regex the subject is expected to match.
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  matches(regex, opt_message) {
+    if (!(regex instanceof RegExp)) {
+      throw TypeError(`Not a RegExp: ${describe(regex)}`);
+    }
+    return evaluate(this.subject_, function(actual) {
+      if (!isString(actual) || !regex.test(actual)) {
+        let message = opt_message
+            || `Expected a string matching ${regex}, got ${describe(actual)}`;
+        assert.fail(actual, regex, message);
+      }
+    });
+  }
+
+  /**
+   * @param {?} value The unexpected value.
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  notEqualTo(value, opt_message) {
+    return evaluate(this.subject_, function(actual) {
+      assert.notStrictEqual(actual, value, opt_message);
+    });
+  }
+
+  /** An alias for {@link #isEqualTo}. */
+  equalTo(value, opt_message) {
+    return this.isEqualTo(value, opt_message);
+  }
+
+  /** An alias for {@link #isEqualTo}. */
+  equals(value, opt_message) {
+    return this.isEqualTo(value, opt_message);
+  }
+
+  /**
+   * @param {?} value The expected value.
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  isEqualTo(value, opt_message) {
+    return evaluate(this.subject_, function(actual) {
+      assert.strictEqual(actual, value, opt_message);
+    });
+  }
+
+  /**
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  isTrue(opt_message) {
+    return this.isEqualTo(true, opt_message);
+  }
+
+  /**
+   * @param {string=} opt_message An optional failure message.
+   * @return {(Promise|undefined)} The result of this assertion, if the subject
+   *     is a promised-value. Otherwise, the assertion is performed immediately
+   *     and nothing is returned.
+   */
+  isFalse(opt_message) {
+    return this.isEqualTo(false, opt_message);
+  }
+}
+
+
+// PUBLIC API
 
 
 /**
- * Registers a new assertion to expose from the
- * {@link webdriver.testing.Assertion} prototype.
- * @param {string} name The assertion name.
- * @param {(function(new: goog.labs.testing.Matcher, *)|
- *          {matches: function(*): boolean,
- *           describe: function(): string})} matcherTemplate Either the
- *     matcher constructor to use, or an object literal defining a matcher.
+ * Creates an assertion about the given `value`.
+ * @return {!Assertion} the new assertion.
  */
-module.exports.register = assert.register;
+module.exports = function assertThat(value) {
+  return new Assertion(value);
+};
+module.exports.Assertion = Assertion;  // Exported to help generated docs

package/testing/index.js

@@ -189,6 +189,16 @@ function ignore(predicateFn) {
 
 // PUBLIC API
 
+
+/**
+ * @return {!promise.ControlFlow} the control flow instance used by this module
+ *     to coordinate test actions.
+ */
+exports.controlFlow = function(){
+  return flow;
+};
+
+
 /**
  * Registers a new test suite.
  * @param {string} name The suite name.

package/_base.js

@@ -1,200 +0,0 @@
-// Licensed to the Software Freedom Conservancy (SFC) under one
-// or more contributor license agreements.  See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership.  The SFC licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License.  You may obtain a copy of the License at
-//
-//   http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied.  See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-/**
- * @fileoverview The base module responsible for bootstrapping the Closure
- * library and providing a means of loading Closure-based modules.
- *
- * <p>Each script loaded by this module will be granted access to this module's
- * {@code require} function; all required non-native modules must be specified
- * relative to <em>this</em> module.
- *
- * <p>This module will load all scripts from the "lib" subdirectory, unless the
- * SELENIUM_DEV_MODE environment variable has been set to 1, in which case all
- * scripts will be loaded from the Selenium client containing this script.
- */
-
-'use strict';
-
-var fs = require('fs'),
-    path = require('path'),
-    vm = require('vm');
-
-
-/**
- * If this script was loaded from the Selenium project repo, it will operate in
- * development mode, adjusting how it loads Closure-based dependencies.
- * @type {boolean}
- */
-var devMode = (function() {
-  var buildDescFile = path.join(__dirname, '..', 'build.desc');
-  return fs.existsSync(buildDescFile);
-})();
-
-
-/** @return {boolean} Whether this script was loaded in dev mode. */
-function isDevMode() {
-  return devMode;
-}
-
-
-/**
- * @type {string} Path to Closure's base file, relative to this module.
- * @const
- */
-var CLOSURE_BASE_FILE_PATH = (function() {
-  var relativePath = isDevMode() ?
-      '../../../third_party/closure/goog/base.js' :
-      './lib/goog/base.js';
-  return path.join(__dirname, relativePath);
-})();
-
-
-/**
- * @type {string} Path to Closure's base file, relative to this module.
- * @const
- */
-var DEPS_FILE_PATH = (function() {
-  var relativePath = isDevMode() ?
-      '../../../javascript/deps.js' :
-      './lib/goog/deps.js';
-  return path.join(__dirname, relativePath);
-})();
-
-
-/**
- * Maintains a unique context for Closure library-based code.
- * @param {boolean=} opt_configureForTesting Whether to configure a fake DOM
- *     for Closure-testing code that (incorrectly) assumes a DOM is always
- *     present.
- * @constructor
- */
-function Context(opt_configureForTesting) {
-  var closure = this.closure = vm.createContext({
-    console: console,
-    setTimeout: setTimeout,
-    setInterval: setInterval,
-    clearTimeout: clearTimeout,
-    clearInterval: clearInterval,
-    process: process,
-    require: require,
-    Buffer: Buffer,
-    Error: Error,
-    TypeError: TypeError,
-    CLOSURE_BASE_PATH: path.dirname(CLOSURE_BASE_FILE_PATH) + '/',
-    CLOSURE_IMPORT_SCRIPT: function(src, opt_srcText) {
-      if (opt_srcText !== undefined) {
-        // Windows paths use backslashes, which must be properly escaped before
-        // evaluated with vm.runInContext.
-        opt_srcText = opt_srcText.replace(/\\/g, '/');
-        vm.runInContext(opt_srcText, closure, src);
-      } else {
-        loadScript(src);
-      }
-      return true;
-    },
-    CLOSURE_NO_DEPS: !isDevMode(),
-    CLOSURE_UNCOMPILED_DEFINES: {'goog.json.USE_NATIVE_JSON': true},
-    goog: {}
-  });
-  closure.window = closure.top = closure;
-
-  if (opt_configureForTesting) {
-    closure.document = {
-      body: {},
-      createElement: function() { return {}; },
-      getElementsByTagName: function() { return []; }
-    };
-    closure.document.body.ownerDocument = closure.document;
-  }
-
-  loadScript(CLOSURE_BASE_FILE_PATH);
-  loadScript(DEPS_FILE_PATH);
-
-  // Redefine retrieveAndExecModule_ to load modules. Closure's version
-  // assumes XMLHttpRequest is defined (and by extension that scripts
-  // are being loaded from a server).
-  closure.goog.retrieveAndExecModule_ = function(src) {
-    var normalizedSrc = path.normalize(src);
-    var contents = fs.readFileSync(normalizedSrc, 'utf8');
-    contents = closure.goog.wrapModule_(src, contents);
-    vm.runInContext(contents, closure, normalizedSrc);
-  };
-
-  /**
-   * Synchronously loads a script into the protected Closure context.
-   * @param {string} src Path to the file to load.
-   */
-  function loadScript(src) {
-    src = path.normalize(src);
-    var contents = fs.readFileSync(src, 'utf8');
-    vm.runInContext(contents, closure, src);
-  }
-}
-
-
-var context = new Context();
-
-
-/**
- * Loads a symbol by name from the protected Closure context.
- * @param {string} symbol The symbol to load.
- * @return {?} The loaded symbol, or {@code null} if not found.
- * @throws {Error} If the symbol has not been defined.
- */
-function closureRequire(symbol) {
-  context.closure.goog.require(symbol);
-  return context.closure.goog.getObjectByName(symbol);
-}
-
-
-// PUBLIC API
-
-
-/**
- * Loads a symbol by name from the protected Closure context and exports its
- * public API to the provided object. This function relies on Closure code
- * conventions to define the public API of an object as those properties whose
- * name does not end with "_".
- * @param {string} symbol The symbol to load. This must resolve to an object.
- * @return {!Object} An object with the exported API.
- * @throws {Error} If the symbol has not been defined or does not resolve to
- *     an object.
- */
-exports.exportPublicApi = function(symbol) {
-  var src = closureRequire(symbol);
-  if (typeof src != 'object' || src === null) {
-    throw Error('"' + symbol + '" must resolve to an object');
-  }
-
-  var dest = {};
-  Object.keys(src).forEach(function(key) {
-    if (key[key.length - 1] != '_') {
-      dest[key] = src[key];
-    }
-  });
-
-  return dest;
-};
-
-
-if (isDevMode()) {
-  exports.closure = context.closure;
-}
-exports.Context = Context;
-exports.isDevMode = isDevMode;
-exports.require = closureRequire;