selenium-webdriver 2.48.2 → 2.53.3

package/edge.js

@@ -0,0 +1,378 @@
+// 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 Defines a {@linkplain Driver WebDriver} client for
+ * Microsoft's Edge web browser. Before using this module,
+ * you must download and install the latest
+ * [MicrosoftEdgeDriver](http://go.microsoft.com/fwlink/?LinkId=619687) server.
+ * Ensure that the MicrosoftEdgeDriver is on your
+ * [PATH](http://en.wikipedia.org/wiki/PATH_%28variable%29).
+ *
+ * There are three primary classes exported by this module:
+ *
+ * 1. {@linkplain ServiceBuilder}: configures the
+ *     {@link ./remote.DriverService remote.DriverService}
+ *     that manages the [MicrosoftEdgeDriver] child process.
+ *
+ * 2. {@linkplain Options}: defines configuration options for each new
+ *     MicrosoftEdgeDriver session, such as which
+ *     {@linkplain Options#setProxy proxy} to use when starting the browser.
+ *
+ * 3. {@linkplain Driver}: the WebDriver client; each new instance will control
+ *     a unique browser session.
+ *
+ * __Customizing the MicrosoftEdgeDriver Server__ <a id="custom-server"></a>
+ *
+ * By default, every MicrosoftEdge session will use a single driver service,
+ * which is started the first time a {@link Driver} instance is created and
+ * terminated when this process exits. The default service will inherit its
+ * environment from the current process.
+ * You may obtain a handle to this default service using
+ * {@link #getDefaultService getDefaultService()} and change its configuration
+ * with {@link #setDefaultService setDefaultService()}.
+ *
+ * You may also create a {@link Driver} with its own driver service. This is
+ * useful if you need to capture the server's log output for a specific session:
+ *
+ *     var edge = require('selenium-webdriver/edge');
+ *
+ *     var service = new edge.ServiceBuilder()
+ *         .usingPort(55555)
+ *         .build();
+ *
+ *     var options = new edge.Options();
+ *     // configure browser options ...
+ *
+ *     var driver = new edge.Driver(options, service);
+ *
+ * Users should only instantiate the {@link Driver} class directly when they
+ * need a custom driver service configuration (as shown above). For normal
+ * operation, users should start MicrosoftEdge using the
+ * {@link ./builder.Builder selenium-webdriver.Builder}.
+ *
+ * [MicrosoftEdgeDriver]: https://msdn.microsoft.com/en-us/library/mt188085(v=vs.85).aspx
+ */
+
+'use strict';
+
+const fs = require('fs'),
+    util = require('util');
+
+const executors = require('./executors'),
+    io = require('./io'),
+    capabilities = require('./lib/capabilities'),
+    promise = require('./lib/promise'),
+    Symbols = require('./lib/symbols'),
+    webdriver = require('./lib/webdriver'),
+    portprober = require('./net/portprober'),
+    remote = require('./remote');
+
+const EDGEDRIVER_EXE = 'MicrosoftWebDriver.exe';
+
+
+/**
+ * Option keys.
+ * @enum {string}
+ */
+const CAPABILITY_KEY = {
+  PAGE_LOAD_STRATEGY: 'pageLoadStrategy'
+};
+
+
+/**
+ * Class for managing MicrosoftEdgeDriver specific options.
+ */
+class Options {
+  constructor() {
+    /** @private {!Object} */
+    this.options_ = {};
+
+    /** @private {?capabilities.ProxyConfig} */
+    this.proxy_ = null;
+  }
+
+  /**
+   * Extracts the MicrosoftEdgeDriver specific options from the given
+   * capabilities object.
+   * @param {!capabilities.Capabilities} caps The capabilities object.
+   * @return {!Options} The MicrosoftEdgeDriver options.
+   */
+  static fromCapabilities(caps) {
+    var options = new Options();
+    var map = options.options_;
+
+    Object.keys(CAPABILITY_KEY).forEach(function(key) {
+      key = CAPABILITY_KEY[key];
+      if (caps.has(key)) {
+        map[key] = caps.get(key);
+      }
+    });
+
+    if (caps.has(capabilities.Capability.PROXY)) {
+      options.setProxy(caps.get(capabilities.Capability.PROXY));
+    }
+
+    return options;
+  }
+
+  /**
+   * Sets the proxy settings for the new session.
+   * @param {capabilities.ProxyConfig} proxy The proxy configuration to use.
+   * @return {!Options} A self reference.
+   */
+  setProxy(proxy) {
+    this.proxy_ = proxy;
+    return this;
+  }
+
+  /**
+   * Sets the page load strategy for Edge.
+   * Supported values are "normal", "eager", and "none";
+   *
+   * @param {string} pageLoadStrategy The page load strategy to use.
+   * @return {!Options} A self reference.
+   */
+  setPageLoadStrategy(pageLoadStrategy) {
+    this.options_[CAPABILITY_KEY.PAGE_LOAD_STRATEGY] =
+      pageLoadStrategy.toLowerCase();
+    return this;
+  }
+
+  /**
+   * Converts this options instance to a {@link capabilities.Capabilities}
+   * object.
+   * @param {capabilities.Capabilities=} opt_capabilities The capabilities to
+   *     merge these options into, if any.
+   * @return {!capabilities.Capabilities} The capabilities.
+   */
+  toCapabilities(opt_capabilities) {
+    var caps = opt_capabilities || capabilities.Capabilities.edge();
+    if (this.proxy_) {
+      caps.set(capabilities.Capability.PROXY, this.proxy_);
+    }
+    Object.keys(this.options_).forEach(function(key) {
+      caps.set(key, this.options_[key]);
+    }, this);
+    return caps;
+  }
+
+  /**
+   * Converts this instance to its JSON wire protocol representation. Note this
+   * function is an implementation not intended for general use.
+   * @return {{pageLoadStrategy: (string|undefined)}}
+   *   The JSON wire protocol representation of this instance.
+   */
+  [Symbols.serialize]() {
+    var json = {};
+    for (var key in this.options_) {
+      if (this.options_[key] != null) {
+        json[key] = this.options_[key];
+      }
+    }
+    return json;
+  }
+}
+
+
+/**
+ * Creates {@link remote.DriverService} instances that manage a
+ * MicrosoftEdgeDriver server in a child process.
+ */
+class ServiceBuilder {
+  /**
+   * @param {string=} opt_exe Path to the server executable to use. If omitted,
+   *   the builder will attempt to locate the MicrosoftEdgeDriver on the current
+   *   PATH.
+   * @throws {Error} If provided executable does not exist, or the
+   *   MicrosoftEdgeDriver cannot be found on the PATH.
+   */
+  constructor(opt_exe) {
+    let exe = opt_exe || io.findInPath(EDGEDRIVER_EXE, true);
+    if (!exe) {
+      throw Error(
+        'The ' + EDGEDRIVER_EXE + ' could not be found on the current PATH. ' +
+        'Please download the latest version of the MicrosoftEdgeDriver from ' +
+        'https://www.microsoft.com/en-us/download/details.aspx?id=48212 and ' +
+        'ensure it can be found on your PATH.');
+    } else if (!fs.existsSync(exe)) {
+      throw Error('File does not exist: ' + exe);
+    }
+
+    /** @private {string} */
+    this.exe_ = /** @type {string} */(exe);
+
+    /** @private {!Array.<string>} */
+    this.args_ = [];
+
+    /** @private {number} */
+    this.port_ = 0;
+
+    /**
+     * @private {(string|!Array.<string|number|!stream.Stream|null|undefined>)}
+     */
+    this.stdio_ = 'ignore';
+
+    /** @private {Object.<string, string>} */
+    this.env_ = null;
+  }
+
+  /**
+   * Defines the stdio configuration for the driver service. See
+   * {@code child_process.spawn} for more information.
+   * @param {(string|!Array.<string|number|!stream.Stream|null|undefined>)}
+   *     config The configuration to use.
+   * @return {!ServiceBuilder} A self reference.
+   */
+  setStdio(config) {
+    this.stdio_ = config;
+    return this;
+  }
+
+  /**
+   * Sets the port to start the MicrosoftEdgeDriver on.
+   * @param {number} port The port to use, or 0 for any free port.
+   * @return {!ServiceBuilder} A self reference.
+   * @throws {Error} If the port is invalid.
+   */
+  usingPort(port) {
+    if (port < 0) {
+      throw Error('port must be >= 0: ' + port);
+    }
+    this.port_ = port;
+    return this;
+  }
+
+  /**
+   * Defines the environment to start the server under. This settings will be
+   * inherited by every browser session started by the server.
+   * @param {!Object.<string, string>} env The environment to use.
+   * @return {!ServiceBuilder} A self reference.
+   */
+  withEnvironment(env) {
+    this.env_ = env;
+    return this;
+  }
+
+  /**
+   * Creates a new DriverService using this instance's current configuration.
+   * @return {!remote.DriverService} A new driver service using this instance's
+   *     current configuration.
+   * @throws {Error} If the driver exectuable was not specified and a default
+   *     could not be found on the current PATH.
+   */
+  build() {
+    var port = this.port_ || portprober.findFreePort();
+    var args = this.args_.concat();  // Defensive copy.
+
+    return new remote.DriverService(this.exe_, {
+      // Binding to the loopback address will fail if not running with
+      // administrator privileges. Since we cannot test for that in script
+      // (or can we?), force the DriverService to use "localhost".
+      hostname: 'localhost',
+      port: port,
+      args: promise.fulfilled(port).then(function(port) {
+        return args.concat('--port=' + port);
+      }),
+      env: this.env_,
+      stdio: this.stdio_
+    });
+  }
+}
+
+
+/** @type {remote.DriverService} */
+var defaultService = null;
+
+
+/**
+ * Sets the default service to use for new MicrosoftEdgeDriver instances.
+ * @param {!remote.DriverService} service The service to use.
+ * @throws {Error} If the default service is currently running.
+ */
+function setDefaultService(service) {
+  if (defaultService && defaultService.isRunning()) {
+    throw Error(
+      'The previously configured EdgeDriver service is still running. ' +
+      'You must shut it down before you may adjust its configuration.');
+  }
+  defaultService = service;
+}
+
+
+/**
+ * Returns the default MicrosoftEdgeDriver service. If such a service has
+ * not been configured, one will be constructed using the default configuration
+ * for an MicrosoftEdgeDriver executable found on the system PATH.
+ * @return {!remote.DriverService} The default MicrosoftEdgeDriver service.
+ */
+function getDefaultService() {
+  if (!defaultService) {
+    defaultService = new ServiceBuilder().build();
+  }
+  return defaultService;
+}
+
+
+/**
+ * Creates a new WebDriver client for Microsoft's Edge.
+ */
+class Driver extends webdriver.WebDriver {
+  /**
+   * @param {(capabilities.Capabilities|Options)=} opt_config The configuration
+   *     options.
+   * @param {remote.DriverService=} opt_service The session to use; will use
+   *     the {@linkplain #getDefaultService default service} by default.
+   * @param {promise.ControlFlow=} opt_flow The control flow to use, or
+   *     {@code null} to use the currently active flow.
+   */
+  constructor(opt_config, opt_service, opt_flow) {
+    var service = opt_service || getDefaultService();
+    var executor = executors.createExecutor(service.start());
+
+    var caps =
+        opt_config instanceof Options ? opt_config.toCapabilities() :
+        (opt_config || capabilities.Capabilities.edge());
+
+    var driver = webdriver.WebDriver.createSession(executor, caps, opt_flow);
+    super(driver.getSession(), executor, driver.controlFlow());
+
+    var boundQuit = this.quit.bind(this);
+
+    /** @override */
+    this.quit = function() {
+      return boundQuit().thenFinally(service.kill.bind(service));
+    };
+  }
+
+  /**
+   * This function is a no-op as file detectors are not supported by this
+   * implementation.
+   * @override
+   */
+  setFileDetector() {}
+}
+
+
+// PUBLIC API
+
+
+exports.Driver = Driver;
+exports.Options = Options;
+exports.ServiceBuilder = ServiceBuilder;
+exports.getDefaultService = getDefaultService;
+exports.setDefaultService = setDefaultService;

package/error.js

@@ -17,11 +17,14 @@
 
 'use strict';
 
-var base = require('./_base');
+/**
+ * @fileoverview Deprecated error module alias. Use
+ * {@linkplain ./lib/error selenium-webdriver/lib/error} or the `error` property
+ * exported by the {@linkplain ./index.error main} module.
+ *
+ * @deprecated
+ */
 
+const error = require('./lib/error');
 
-/** @type {function(new: bot.Error)} */
-exports.Error = base.require('bot.Error');
-
-/** @type {bot.ErrorCode.} */
-exports.ErrorCode = base.require('bot.ErrorCode');
+module.exports = error;

package/example/google_search.js

@@ -30,7 +30,7 @@
  *   SELENIUM_SERVER_JAR=/path/to/selenium-server-standalone.jar \
  *     node selenium-webdriver/example/google_search.js
  *
- *   // Target a remove Selenium server
+ *   // Target a remote Selenium server
  *   SELENIUM_REMOTE_URL=http://www.example.com:4444/wd/hub \
  *     node selenium-webdriver/example/google_search.js
  */

package/example/google_search_generator.js

@@ -16,11 +16,9 @@
 // under the License.
 
 /**
- * @fileoverview An example WebDriver script using Harmony generator functions.
- * This requires node v0.11 or newer.
+ * @fileoverview An example WebDriver script using generator functions.
  *
- * Usage: node --harmony-generators \
- *     selenium-webdriver/example/google_search_generator.js
+ * Usage: node selenium-webdriver/example/google_search_generator.js
  */
 
 var webdriver = require('..'),

package/example/logging.js

@@ -26,14 +26,18 @@ var webdriver = require('..'),
     until = webdriver.until;
 
 webdriver.logging.installConsoleHandler();
-webdriver.logging.getLogger().setLevel(webdriver.logging.Level.ALL);
+webdriver.logging.getLogger('webdriver.http')
+    .setLevel(webdriver.logging.Level.ALL);
 
 var driver = new webdriver.Builder()
     .forBrowser('firefox')
     .build();
 
 driver.get('http://www.google.com/ncr');
-driver.findElement(By.name('q')).sendKeys('webdriver');
+
+var searchBox = driver.wait(until.elementLocated(By.name('q')), 3000);
+searchBox.sendKeys('webdriver');
+
 driver.findElement(By.name('btnG')).click();
 driver.wait(until.titleIs('webdriver - Google Search'), 1000);
 driver.quit();

package/example/sample.js

@@ -0,0 +1,21 @@
+// Load the http module to create an http server.
+var http = require('http');
+
+http.createServer(function (request, response) {
+  response.writeHead(200, {"Content-Type": "text/html"});
+  response.end(`<!DOCTYPE html><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=no"><meta http-equiv="Content-Language" content="en"><meta http-equiv="X-UA-Compatible" content="IE=edge"><title>Index</title><link href="dossier.css" rel="stylesheet" type="text/css"><header><div><form><div><input type="search" placeholder="Search"></div></form></div></header><main><article class="indexfile"><h1>Closure Generated API Docs</h1><p>This is the generated documentation for the Closure Library repository at <a href="http://github.com/google/closure-library">github.com/google/closure-library</a>.</p><p>The documentation was produced using <a href="http://github.com/jleyba/js-dossier">github.com/jleyba/js-dossier</a></p></article><nav><h3><a href="index.html">Overview</a></h3><div><input type="checkbox" id="nav-types" checked/><label for="nav-types"><h3><span class="selectable">Types</span></h3></label><div id="nav-types-view"></div></div></nav></main><div class="pre-footer"><div></div></div><footer><div><a href="https://github.com/jleyba/js-dossier">Generated by dossier</a></div></footer><script src="types.js"></script><script src="dossier.js"></script>`);
+}).listen(8000);
+
+http.createServer(function (request, response) {
+  response.writeHead(200, {"Content-Type": "text/html"});
+  response.end(`<!DOCTYPE html><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=no"><meta http-equiv="Content-Language" content="en"><meta http-equiv="X-UA-Compatible" content="IE=edge"><link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet"><title>Index</title><link href="dossier.css" rel="stylesheet" type="text/css"><header><button class="dossier-menu"><i class="material-icons">menu</i></button><form><input type="search" placeholder="Search" tabindex="1"><i class="material-icons">search</i></form></header><div class="content"><main><article class="page"><h1>Closure Generated API Docs</h1>
+<p>This is the generated documentation for the Closure Library
+repository at
+<a href="http://github.com/google/closure-library">github.com/google/closure-library</a>.</p>
+<p>The documentation was produced using
+<a href="http://github.com/jleyba/js-dossier">github.com/jleyba/js-dossier</a></p>
+</article></main><footer><div><a href="https://github.com/jleyba/js-dossier">Generated by dossier</a></div></footer></div><nav class="dossier-nav"><section><a class="title" href="index.html" tabindex="2">Overview</a></section><section class="types"><div class="toggle"><div class="title"><span class="item" tabindex="2">Types</span><i class="material-icons">expand_more</i></div></div></section></nav><script src="types.js"></script><script src="dossier.js"></script>`);
+}).listen(9000);
+
+console.log("Hello server running at http://127.0.0.1:8000/");
+console.log("Goodbye server running at http://127.0.0.1:9000/");

package/executors.js

@@ -16,47 +16,31 @@
 // under the License.
 
 /**
- * @fileoverview Various utilities for working with
- * {@link webdriver.CommandExecutor} implementations.
+ * @fileoverview Various utilities for working with {@link ./command.Executor}
+ * implementations.
  */
 
-var HttpClient = require('./http').HttpClient,
-    HttpExecutor = require('./http').Executor,
-    promise = require('./_base').require('webdriver.promise');
-
-
-
-/**
- * Wraps a promised {@link webdriver.CommandExecutor}, ensuring no commands
- * are executed until the wrapped executor has been fully built.
- * @param {!webdriver.promise.Promise.<!webdriver.CommandExecutor>} delegate The
- *     promised delegate.
- * @constructor
- * @implements {webdriver.CommandExecutor}
- */
-var DeferredExecutor = function(delegate) {
+ 'use strict';
 
-  /** @override */
-  this.execute = function(command, callback) {
-    delegate.then(function(executor) {
-      executor.execute(command, callback);
-    }, callback);
-  };
-};
+const HttpClient = require('./http').HttpClient,
+    HttpExecutor = require('./http').Executor,
+    DeferredExecutor = require('./lib/command').DeferredExecutor,
+    promise = require('./lib/promise');
 
 
 // PUBLIC API
 
 
+/** @deprecated Use {@link ./lib/command.DeferredExecutor} instead. */
 exports.DeferredExecutor = DeferredExecutor;
 
 /**
  * Creates a command executor that uses WebDriver's JSON wire protocol.
- * @param {(string|!webdriver.promise.Promise.<string>)} url The server's URL,
+ * @param {(string|!promise.Promise<string>)} url The server's URL,
  *     or a promise that will resolve to that URL.
- * @param {string=} opt_proxy (optional) The URL of the HTTP proxy for the
+ * @param {?string=} opt_proxy (optional) The URL of the HTTP proxy for the
  *     client to use.
- * @returns {!webdriver.CommandExecutor} The new command executor.
+ * @returns {!./lib/command.Executor} The new command executor.
  */
 exports.createExecutor = function(url, opt_proxy) {
   return new DeferredExecutor(promise.when(url, function(url) {