selenium-webdriver 2.48.2 → 2.53.3

package/index.js

@@ -20,129 +20,38 @@
  * public API and provides convenience assessors to certain sub-modules.
  */
 
-var base = require('./_base');
-var builder = require('./builder');
-var error = require('./error');
-
-
-// NOTE: the remainder of this file is nasty and verbose, but the annotations
-// are necessary to guide the Closure Compiler's type analysis. Without them,
-// we would not be able to extract any meaningful API documentation.
-
-
-/** @type {function(new: webdriver.ActionSequence)} */
-exports.ActionSequence = base.require('webdriver.ActionSequence');
-
-
-/** @type {function(new: builder.Builder)} */
+'use strict';
+
+const builder = require('./builder');
+const actions = require('./lib/actions');
+const by = require('./lib/by');
+const capabilities = require('./lib/capabilities');
+const command = require('./lib/command');
+const error = require('./lib/error');
+const events = require('./lib/events');
+const input = require('./lib/input');
+const logging = require('./lib/logging');
+const promise = require('./lib/promise');
+const session = require('./lib/session');
+const until = require('./lib/until');
+const webdriver = require('./lib/webdriver');
+
+
+exports.ActionSequence = actions.ActionSequence;
+exports.Browser = capabilities.Browser;
 exports.Builder = builder.Builder;
-
-
-/** @type {webdriver.By.} */
-exports.By = base.require('webdriver.By');
-
-
-/** @type {function(new: webdriver.Capabilities)} */
-exports.Capabilities = base.require('webdriver.Capabilities');
-
-
-/** @type {function(new: webdriver.Command)} */
-exports.Command = base.require('webdriver.Command');
-
-
-/** @type {function(new: webdriver.EventEmitter)} */
-exports.EventEmitter = base.require('webdriver.EventEmitter');
-
-
-/** @type {function(new: webdriver.FileDetector)} */
-exports.FileDetector = base.require('webdriver.FileDetector');
-
-
-/** @type {function(new: webdriver.Serializable)} */
-exports.Serializable = base.require('webdriver.Serializable');
-
-
-/** @type {function(new: webdriver.Session)} */
-exports.Session = base.require('webdriver.Session');
-
-
-/** @type {function(new: webdriver.WebDriver)} */
-exports.WebDriver = base.require('webdriver.WebDriver');
-
-
-/** @type {function(new: webdriver.WebElement)} */
-exports.WebElement = base.require('webdriver.WebElement');
-
-
-/** @type {function(new: webdriver.WebElementPromise)} */
-exports.WebElementPromise = base.require('webdriver.WebElementPromise');
-
-
-// Export the remainder of our API through getters to keep things cleaner
-// when this module is used in a REPL environment.
-
-
-/** @type {webdriver.Browser.} */
-(exports.__defineGetter__('Browser', function() {
-  return base.require('webdriver.Browser');
-}));
-
-
-/** @type {webdriver.Button.} */
-(exports.__defineGetter__('Button', function() {
-  return base.require('webdriver.Button');
-}));
-
-
-/** @type {webdriver.Capability.} */
-(exports.__defineGetter__('Capability', function() {
-  return base.require('webdriver.Capability');
-}));
-
-
-/** @type {webdriver.CommandName.} */
-(exports.__defineGetter__('CommandName', function() {
-  return base.require('webdriver.CommandName');
-}));
-
-
-/** @type {webdriver.Key.} */
-(exports.__defineGetter__('Key', function() {
-  return base.require('webdriver.Key');
-}));
-
-
-/** @type {error.} */
-(exports.__defineGetter__('error', function() {
-  return error;
-}));
-
-
-/** @type {error.} */
-(exports.__defineGetter__('error', function() {
-  return error;
-}));
-
-
-/** @type {webdriver.logging.} */
-(exports.__defineGetter__('logging', function() {
-  return base.exportPublicApi('webdriver.logging');
-}));
-
-
-/** @type {webdriver.promise.} */
-(exports.__defineGetter__('promise', function() {
-  return base.exportPublicApi('webdriver.promise');
-}));
-
-
-/** @type {webdriver.stacktrace.} */
-(exports.__defineGetter__('stacktrace', function() {
-  return base.exportPublicApi('webdriver.stacktrace');
-}));
-
-
-/** @type {webdriver.until.} */
-(exports.__defineGetter__('until', function() {
-  return base.exportPublicApi('webdriver.until');
-}));
+exports.Button = input.Button;
+exports.By = by.By;
+exports.Capabilities = capabilities.Capabilities;
+exports.Capability = capabilities.Capability;
+exports.EventEmitter = events.EventEmitter;
+exports.FileDetector = input.FileDetector;
+exports.Key = input.Key;
+exports.Session = session.Session;
+exports.WebDriver = webdriver.WebDriver;
+exports.WebElement = webdriver.WebElement;
+exports.WebElementPromise = webdriver.WebElementPromise;
+exports.error = error;
+exports.logging = logging;
+exports.promise = promise;
+exports.until = until;

package/io/exec.js

@@ -17,9 +17,8 @@
 
 'use strict';
 
-var childProcess = require('child_process');
-
-var promise = require('..').promise;
+const childProcess = require('child_process');
+const promise = require('../lib/promise');
 
 
 /**
@@ -32,9 +31,10 @@ var promise = require('..').promise;
  *     information, refer to the documentation of `child_process.spawn`.
  *
  * @typedef {{
- *   args: (!Array.<string>|undefined),
- *   env: (!Object.<string, string>|undefined),
- *   stdio: (string|!Array.<string|number|!Stream|null|undefined>|undefined)
+ *   args: (!Array<string>|undefined),
+ *   env: (!Object<string, string>|undefined),
+ *   stdio: (string|!Array<string|number|!stream.Stream|null|undefined>|
+ *           undefined)
  * }}
  */
 var Options;
@@ -42,56 +42,68 @@ var Options;
 
 /**
  * Describes a command's termination conditions.
- * @param {?number} code The exit code, or {@code null} if the command did not
- *     exit normally.
- * @param {?string} signal The signal used to kill the command, or
- *     {@code null}.
- * @constructor
  */
-var Result = function(code, signal) {
-  /** @type {?number} */
-  this.code = code;
-
-  /** @type {?string} */
-  this.signal = signal;
-};
+class Result {
+  /**
+   * @param {?number} code The exit code, or {@code null} if the command did not
+   *     exit normally.
+   * @param {?string} signal The signal used to kill the command, or
+   *     {@code null}.
+   */
+  constructor(code, signal) {
+    /** @type {?number} */
+    this.code = code;
 
+    /** @type {?string} */
+    this.signal = signal;
+  }
 
-/** @override */
-Result.prototype.toString = function() {
-  return 'Result(code=' + this.code + ', signal=' + this.signal + ')';
-};
+  /** @override */
+  toString() {
+    return `Result(code=${this.code}, signal=${this.signal})`;
+  }
+}
 
 
+const COMMAND_RESULT =
+    /** !WeakMap<!Command, !promise.Promise<!Result>> */new WeakMap;
+const KILL_HOOK = /** !WeakMap<!Command, function(string)> */new WeakMap;
 
 /**
  * Represents a command running in a sub-process.
- * @param {!promise.Promise.<!Result>} result The command result.
- * @constructor
  */
-var Command = function(result, onKill) {
+class Command {
+  /**
+   * @param {!promise.Promise<!Result>} result The command result.
+   * @param {function(string)} onKill The function to call when {@link #kill()}
+   *     is called.
+   */
+  constructor(result, onKill) {
+    COMMAND_RESULT.set(this, result);
+    KILL_HOOK.set(this, onKill);
+  }
+
   /** @return {boolean} Whether this command is still running. */
-  this.isRunning = function() {
-    return result.isPending();
-  };
+  isRunning() {
+    return COMMAND_RESULT.get(this).isPending();
+  }
 
   /**
-   * @return {!promise.Promise.<!Result>} A promise for the result of this
+   * @return {!promise.Promise<!Result>} A promise for the result of this
    *     command.
    */
-  this.result = function() {
-    return result;
-  };
+  result() {
+    return /** @type {!promise.Promise<!Result>} */(COMMAND_RESULT.get(this));
+  }
 
   /**
    * Sends a signal to the underlying process.
-   * @param {string=} opt_signal The signal to send; defaults to
-   *     {@code SIGTERM}.
+   * @param {string=} opt_signal The signal to send; defaults to `SIGTERM`.
    */
-  this.kill = function(opt_signal) {
-    onKill(opt_signal || 'SIGTERM');
-  };
-};
+  kill(opt_signal) {
+    KILL_HOOK.get(this)(opt_signal || 'SIGTERM');
+  }
+}
 
 
 // PUBLIC API
@@ -105,7 +117,7 @@ var Command = function(result, onKill) {
  * @param {Options=} opt_options The command options.
  * @return {!Command} The launched command.
  */
-module.exports = function(command, opt_options) {
+module.exports = function exec(command, opt_options) {
   var options = opt_options || {};
 
   var proc = childProcess.spawn(command, options.args || [], {
@@ -138,3 +150,10 @@ module.exports = function(command, opt_options) {
     proc && proc.kill('SIGTERM');
   }
 };
+
+// Exported to improve generated API documentation.
+
+module.exports.Command = Command;
+/** @typedef {!Options} */
+module.exports.Options = Options;
+module.exports.Result = Result;

package/io/index.js

@@ -15,13 +15,13 @@
 // specific language governing permissions and limitations
 // under the License.
 
+'use strict';
+
 var fs = require('fs'),
     path = require('path'),
     rimraf = require('rimraf'),
     tmp = require('tmp');
 
-var promise = require('..').promise;
-
 
 
 // PUBLIC API
@@ -31,17 +31,17 @@ var promise = require('..').promise;
 /**
  * Recursively removes a directory and all of its contents. This is equivalent
  * to {@code rm -rf} on a POSIX system.
- * @param {string} path Path to the directory to remove.
- * @return {!promise.Promise} A promise to be resolved when the operation has
+ * @param {string} dirPath Path to the directory to remove.
+ * @return {!Promise} A promise to be resolved when the operation has
  *     completed.
  */
-exports.rmDir = function(path) {
-  return new promise.Promise(function(fulfill, reject) {
+exports.rmDir = function(dirPath) {
+  return new Promise(function(fulfill, reject) {
     var numAttempts = 0;
     attemptRm();
     function attemptRm() {
       numAttempts += 1;
-      rimraf(path, function(err) {
+      rimraf(dirPath, function(err) {
         if (err) {
           if (err.code === 'ENOTEMPTY' && numAttempts < 2) {
             attemptRm();
@@ -61,23 +61,19 @@ exports.rmDir = function(path) {
  * Copies one file to another.
  * @param {string} src The source file.
  * @param {string} dst The destination file.
- * @return {!promise.Promise.<string>} A promise for the copied file's path.
+ * @return {!Promise<string>} A promise for the copied file's path.
  */
 exports.copy = function(src, dst) {
-  var copied = promise.defer();
-
-  var rs = fs.createReadStream(src);
-  rs.on('error', copied.reject);
-  rs.on('end', function() {
-    copied.fulfill(dst);
-  });
-
-  var ws = fs.createWriteStream(dst);
-  ws.on('error', copied.reject);
+  return new Promise(function(fulfill, reject) {
+    var rs = fs.createReadStream(src);
+    rs.on('error', reject);
+    rs.on('end', () => fulfill(dst));
 
-  rs.pipe(ws);
+    var ws = fs.createWriteStream(dst);
+    ws.on('error', reject);
 
-  return copied.promise;
+    rs.pipe(ws);
+  });
 };
 
 
@@ -85,10 +81,10 @@ exports.copy = function(src, dst) {
  * Recursively copies the contents of one directory to another.
  * @param {string} src The source directory to copy.
  * @param {string} dst The directory to copy into.
- * @param {(RegEx|function(string): boolean)=} opt_exclude An exclusion filter
+ * @param {(RegExp|function(string): boolean)=} opt_exclude An exclusion filter
  *     as either a regex or predicate function. All files matching this filter
  *     will not be copied.
- * @return {!promise.Promise.<string>} A promise for the destination
+ * @return {!Promise<string>} A promise for the destination
  *     directory's path once all files have been copied.
  */
 exports.copyDir = function(src, dst, opt_exclude) {
@@ -110,7 +106,7 @@ exports.copyDir = function(src, dst, opt_exclude) {
   });
 
   if (predicate) {
-    files = files.filter(predicate);
+    files = files.filter(/** @type {function(string): boolean} */(predicate));
   }
 
   var results = [];
@@ -128,35 +124,38 @@ exports.copyDir = function(src, dst, opt_exclude) {
     }
   });
 
-  return promise.all(results).then(function() {
-    return dst;
-  });
+  return Promise.all(results).then(() => dst);
 };
 
 
 /**
  * Tests if a file path exists.
- * @param {string} path The path to test.
- * @return {!promise.Promise.<boolean>} A promise for whether the file exists.
+ * @param {string} aPath The path to test.
+ * @return {!Promise<boolean>} A promise for whether the file exists.
  */
-exports.exists = function(path) {
-  var result = promise.defer();
-  fs.exists(path, result.fulfill);
-  return result.promise;
+exports.exists = function(aPath) {
+  return new Promise(function(fulfill, reject) {
+    let type = typeof aPath;
+    if (type !== 'string') {
+      reject(TypeError(`expected string path, but got ${type}`));
+    } else {
+      fs.exists(aPath, fulfill);
+    }
+  });
 };
 
 
 /**
  * Deletes a name from the filesystem and possibly the file it refers to. Has
  * no effect if the file does not exist.
- * @param {string} path The path to remove.
- * @return {!promise.Promise} A promise for when the file has been removed.
+ * @param {string} aPath The path to remove.
+ * @return {!Promise} A promise for when the file has been removed.
  */
-exports.unlink = function(path) {
-  return new promise.Promise(function(fulfill, reject) {
-    fs.exists(path, function(exists) {
+exports.unlink = function(aPath) {
+  return new Promise(function(fulfill, reject) {
+    fs.exists(aPath, function(exists) {
       if (exists) {
-        fs.unlink(path, function(err) {
+        fs.unlink(aPath, function(err) {
           err && reject(err) || fulfill();
         });
       } else {
@@ -168,27 +167,39 @@ exports.unlink = function(path) {
 
 
 /**
- * @return {!promise.Promise.<string>} A promise for the path to a temporary
- *     directory.
+ * @return {!Promise<string>} A promise for the path to a temporary directory.
  * @see https://www.npmjs.org/package/tmp
  */
 exports.tmpDir = function() {
-  return promise.checkedNodeCall(tmp.dir);
+  return new Promise(function(fulfill, reject) {
+    tmp.dir(function(error, value) {
+      error ? reject(error) : fulfill(value);
+    });
+  });
 };
 
 
 /**
  * @param {{postfix: string}=} opt_options Temporary file options.
- * @return {!promise.Promise.<string>} A promise for the path to a temporary
- *     file.
+ * @return {!Promise<string>} A promise for the path to a temporary file.
  * @see https://www.npmjs.org/package/tmp
  */
 exports.tmpFile = function(opt_options) {
-  // |tmp.file| checks arguments length to detect options rather than doing a
-  // truthy check, so we must only pass options if there are some to pass.
-  return opt_options ?
-      promise.checkedNodeCall(tmp.file, opt_options) :
-      promise.checkedNodeCall(tmp.file);
+  return new Promise(function(fulfill, reject) {
+    let callback = function(
+        /** Error */err,
+        /** (string|undefined) */value) {
+      err ? reject(err) : fulfill(value);
+    };
+
+    // |tmp.file| checks arguments length to detect options rather than doing a
+    // truthy check, so we must only pass options if there are some to pass.
+    if (opt_options) {
+      tmp.file(opt_options, callback);
+    } else {
+      tmp.file(callback);
+    }
+  });
 };
 
 
@@ -202,20 +213,21 @@ exports.tmpFile = function(opt_options) {
  *     not be found.
  */
 exports.findInPath = function(file, opt_checkCwd) {
+  let dirs = [];
   if (opt_checkCwd) {
-    var tmp = path.join(process.cwd(), file);
-    if (fs.existsSync(tmp)) {
-      return tmp;
-    }
+    dirs.push(process.cwd());
   }
-
-  var dirs = process.env['PATH'].split(path.delimiter);
-  var found = null;
-  dirs.forEach(function(dir) {
-    var tmp = path.join(dir, file);
-    if (!found && fs.existsSync(tmp)) {
-      found = tmp;
+  dirs.push.apply(dirs, process.env['PATH'].split(path.delimiter));
+
+  let foundInDir = dirs.find(dir => {
+    let tmp = path.join(dir, file);
+    try {
+      let stats = fs.statSync(tmp);
+      return stats.isFile() && !stats.isDirectory();
+    } catch (ex) {
+      return false;
     }
   });
-  return found;
+
+  return foundInDir ? path.join(foundInDir, file) : null;
 };

package/lib/README

@@ -1,2 +1,6 @@
 This directory contains modules internal to selenium-webdriver that are not
 intended for general consumption. They may change at any time.
+
+With the exception of the test/ directory, all files under this directory
+may only depend on built-in JavaScript features and other modules in the
+directory.