selenium-webdriver 2.47.0 → 2.52.0

package/lib/webdriver/actionsequence.js

@@ -1,356 +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.
-
-goog.provide('webdriver.ActionSequence');
-
-goog.require('goog.array');
-goog.require('webdriver.Button');
-goog.require('webdriver.Command');
-goog.require('webdriver.CommandName');
-goog.require('webdriver.Key');
-
-
-
-/**
- * Class for defining sequences of complex user interactions. Each sequence
- * will not be executed until {@link #perform} is called.
- *
- * Example:
- *
- *     new webdriver.ActionSequence(driver).
- *         keyDown(webdriver.Key.SHIFT).
- *         click(element1).
- *         click(element2).
- *         dragAndDrop(element3, element4).
- *         keyUp(webdriver.Key.SHIFT).
- *         perform();
- *
- * @param {!webdriver.WebDriver} driver The driver instance to use.
- * @constructor
- */
-webdriver.ActionSequence = function(driver) {
-
-  /** @private {!webdriver.WebDriver} */
-  this.driver_ = driver;
-
-  /** @private {!Array.<{description: string, command: !webdriver.Command}>} */
-  this.actions_ = [];
-};
-
-
-/**
- * Schedules an action to be executed each time {@link #perform} is called on
- * this instance.
- * @param {string} description A description of the command.
- * @param {!webdriver.Command} command The command.
- * @private
- */
-webdriver.ActionSequence.prototype.schedule_ = function(description, command) {
-  this.actions_.push({
-    description: description,
-    command: command
-  });
-};
-
-
-/**
- * Executes this action sequence.
- * @return {!webdriver.promise.Promise} A promise that will be resolved once
- *     this sequence has completed.
- */
-webdriver.ActionSequence.prototype.perform = function() {
-  // Make a protected copy of the scheduled actions. This will protect against
-  // users defining additional commands before this sequence is actually
-  // executed.
-  var actions = goog.array.clone(this.actions_);
-  var driver = this.driver_;
-  return driver.controlFlow().execute(function() {
-    goog.array.forEach(actions, function(action) {
-      driver.schedule(action.command, action.description);
-    });
-  }, 'ActionSequence.perform');
-};
-
-
-/**
- * Moves the mouse.  The location to move to may be specified in terms of the
- * mouse's current location, an offset relative to the top-left corner of an
- * element, or an element (in which case the middle of the element is used).
- * @param {(!webdriver.WebElement|{x: number, y: number})} location The
- *     location to drag to, as either another WebElement or an offset in pixels.
- * @param {{x: number, y: number}=} opt_offset If the target {@code location}
- *     is defined as a {@link webdriver.WebElement}, this parameter defines an
- *     offset within that element. The offset should be specified in pixels
- *     relative to the top-left corner of the element's bounding box. If
- *     omitted, the element's center will be used as the target offset.
- * @return {!webdriver.ActionSequence} A self reference.
- */
-webdriver.ActionSequence.prototype.mouseMove = function(location, opt_offset) {
-  var command = new webdriver.Command(webdriver.CommandName.MOVE_TO);
-
-  if (goog.isNumber(location.x)) {
-    setOffset(/** @type {{x: number, y: number}} */(location));
-  } else {
-    command.setParameter('element', location.getRawId());
-    if (opt_offset) {
-      setOffset(opt_offset);
-    }
-  }
-
-  this.schedule_('mouseMove', command);
-  return this;
-
-  /** @param {{x: number, y: number}} offset The offset to use. */
-  function setOffset(offset) {
-    command.setParameter('xoffset', offset.x || 0);
-    command.setParameter('yoffset', offset.y || 0);
-  }
-};
-
-
-/**
- * Schedules a mouse action.
- * @param {string} description A simple descriptive label for the scheduled
- *     action.
- * @param {!webdriver.CommandName} commandName The name of the command.
- * @param {(webdriver.WebElement|webdriver.Button)=} opt_elementOrButton Either
- *     the element to interact with or the button to click with.
- *     Defaults to {@link webdriver.Button.LEFT} if neither an element nor
- *     button is specified.
- * @param {webdriver.Button=} opt_button The button to use. Defaults to
- *     {@link webdriver.Button.LEFT}. Ignored if the previous argument is
- *     provided as a button.
- * @return {!webdriver.ActionSequence} A self reference.
- * @private
- */
-webdriver.ActionSequence.prototype.scheduleMouseAction_ = function(
-    description, commandName, opt_elementOrButton, opt_button) {
-  var button;
-  if (goog.isNumber(opt_elementOrButton)) {
-    button = opt_elementOrButton;
-  } else {
-    if (opt_elementOrButton) {
-      this.mouseMove(
-          /** @type {!webdriver.WebElement} */ (opt_elementOrButton));
-    }
-    button = goog.isDef(opt_button) ? opt_button : webdriver.Button.LEFT;
-  }
-
-  var command = new webdriver.Command(commandName).
-      setParameter('button', button);
-  this.schedule_(description, command);
-  return this;
-};
-
-
-/**
- * Presses a mouse button. The mouse button will not be released until
- * {@link #mouseUp} is called, regardless of whether that call is made in this
- * sequence or another. The behavior for out-of-order events (e.g. mouseDown,
- * click) is undefined.
- *
- * If an element is provided, the mouse will first be moved to the center
- * of that element. This is equivalent to:
- *
- *     sequence.mouseMove(element).mouseDown()
- *
- * Warning: this method currently only supports the left mouse button. See
- * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047).
- *
- * @param {(webdriver.WebElement|webdriver.Button)=} opt_elementOrButton Either
- *     the element to interact with or the button to click with.
- *     Defaults to {@link webdriver.Button.LEFT} if neither an element nor
- *     button is specified.
- * @param {webdriver.Button=} opt_button The button to use. Defaults to
- *     {@link webdriver.Button.LEFT}. Ignored if a button is provided as the
- *     first argument.
- * @return {!webdriver.ActionSequence} A self reference.
- */
-webdriver.ActionSequence.prototype.mouseDown = function(opt_elementOrButton,
-                                                        opt_button) {
-  return this.scheduleMouseAction_('mouseDown',
-      webdriver.CommandName.MOUSE_DOWN, opt_elementOrButton, opt_button);
-};
-
-
-/**
- * Releases a mouse button. Behavior is undefined for calling this function
- * without a previous call to {@link #mouseDown}.
- *
- * If an element is provided, the mouse will first be moved to the center
- * of that element. This is equivalent to:
- *
- *     sequence.mouseMove(element).mouseUp()
- *
- * Warning: this method currently only supports the left mouse button. See
- * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047).
- *
- * @param {(webdriver.WebElement|webdriver.Button)=} opt_elementOrButton Either
- *     the element to interact with or the button to click with.
- *     Defaults to {@link webdriver.Button.LEFT} if neither an element nor
- *     button is specified.
- * @param {webdriver.Button=} opt_button The button to use. Defaults to
- *     {@link webdriver.Button.LEFT}. Ignored if a button is provided as the
- *     first argument.
- * @return {!webdriver.ActionSequence} A self reference.
- */
-webdriver.ActionSequence.prototype.mouseUp = function(opt_elementOrButton,
-                                                      opt_button) {
-  return this.scheduleMouseAction_('mouseUp',
-      webdriver.CommandName.MOUSE_UP, opt_elementOrButton, opt_button);
-};
-
-
-/**
- * Convenience function for performing a "drag and drop" manuever. The target
- * element may be moved to the location of another element, or by an offset (in
- * pixels).
- * @param {!webdriver.WebElement} element The element to drag.
- * @param {(!webdriver.WebElement|{x: number, y: number})} location The
- *     location to drag to, either as another WebElement or an offset in pixels.
- * @return {!webdriver.ActionSequence} A self reference.
- */
-webdriver.ActionSequence.prototype.dragAndDrop = function(element, location) {
-  return this.mouseDown(element).mouseMove(location).mouseUp();
-};
-
-
-/**
- * Clicks a mouse button.
- *
- * If an element is provided, the mouse will first be moved to the center
- * of that element. This is equivalent to:
- *
- *     sequence.mouseMove(element).click()
- *
- * @param {(webdriver.WebElement|webdriver.Button)=} opt_elementOrButton Either
- *     the element to interact with or the button to click with.
- *     Defaults to {@link webdriver.Button.LEFT} if neither an element nor
- *     button is specified.
- * @param {webdriver.Button=} opt_button The button to use. Defaults to
- *     {@link webdriver.Button.LEFT}. Ignored if a button is provided as the
- *     first argument.
- * @return {!webdriver.ActionSequence} A self reference.
- */
-webdriver.ActionSequence.prototype.click = function(opt_elementOrButton,
-                                                    opt_button) {
-  return this.scheduleMouseAction_('click',
-      webdriver.CommandName.CLICK, opt_elementOrButton, opt_button);
-};
-
-
-/**
- * Double-clicks a mouse button.
- *
- * If an element is provided, the mouse will first be moved to the center of
- * that element. This is equivalent to:
- *
- *     sequence.mouseMove(element).doubleClick()
- *
- * Warning: this method currently only supports the left mouse button. See
- * [issue 4047](http://code.google.com/p/selenium/issues/detail?id=4047).
- *
- * @param {(webdriver.WebElement|webdriver.Button)=} opt_elementOrButton Either
- *     the element to interact with or the button to click with.
- *     Defaults to {@link webdriver.Button.LEFT} if neither an element nor
- *     button is specified.
- * @param {webdriver.Button=} opt_button The button to use. Defaults to
- *     {@link webdriver.Button.LEFT}. Ignored if a button is provided as the
- *     first argument.
- * @return {!webdriver.ActionSequence} A self reference.
- */
-webdriver.ActionSequence.prototype.doubleClick = function(opt_elementOrButton,
-                                                          opt_button) {
-  return this.scheduleMouseAction_('doubleClick',
-      webdriver.CommandName.DOUBLE_CLICK, opt_elementOrButton, opt_button);
-};
-
-
-/**
- * Schedules a keyboard action.
- * @param {string} description A simple descriptive label for the scheduled
- *     action.
- * @param {!Array.<(string|!webdriver.Key)>} keys The keys to send.
- * @return {!webdriver.ActionSequence} A self reference.
- * @private
- */
-webdriver.ActionSequence.prototype.scheduleKeyboardAction_ = function(
-    description, keys) {
-  var command =
-      new webdriver.Command(webdriver.CommandName.SEND_KEYS_TO_ACTIVE_ELEMENT).
-          setParameter('value', keys);
-  this.schedule_(description, command);
-  return this;
-};
-
-
-/**
- * Checks that a key is a modifier key.
- * @param {!webdriver.Key} key The key to check.
- * @throws {Error} If the key is not a modifier key.
- * @private
- */
-webdriver.ActionSequence.checkModifierKey_ = function(key) {
-  if (key !== webdriver.Key.ALT && key !== webdriver.Key.CONTROL &&
-      key !== webdriver.Key.SHIFT && key !== webdriver.Key.COMMAND) {
-    throw Error('Not a modifier key');
-  }
-};
-
-
-/**
- * Performs a modifier key press. The modifier key is <em>not released</em>
- * until {@link #keyUp} or {@link #sendKeys} is called. The key press will be
- * targetted at the currently focused element.
- * @param {!webdriver.Key} key The modifier key to push. Must be one of
- *     {ALT, CONTROL, SHIFT, COMMAND, META}.
- * @return {!webdriver.ActionSequence} A self reference.
- * @throws {Error} If the key is not a valid modifier key.
- */
-webdriver.ActionSequence.prototype.keyDown = function(key) {
-  webdriver.ActionSequence.checkModifierKey_(key);
-  return this.scheduleKeyboardAction_('keyDown', [key]);
-};
-
-
-/**
- * Performs a modifier key release. The release is targetted at the currently
- * focused element.
- * @param {!webdriver.Key} key The modifier key to release. Must be one of
- *     {ALT, CONTROL, SHIFT, COMMAND, META}.
- * @return {!webdriver.ActionSequence} A self reference.
- * @throws {Error} If the key is not a valid modifier key.
- */
-webdriver.ActionSequence.prototype.keyUp = function(key) {
-  webdriver.ActionSequence.checkModifierKey_(key);
-  return this.scheduleKeyboardAction_('keyUp', [key]);
-};
-
-
-/**
- * Simulates typing multiple keys. Each modifier key encountered in the
- * sequence will not be released until it is encountered again. All key events
- * will be targetted at the currently focused element.
- * @param {...(string|!webdriver.Key|!Array.<(string|!webdriver.Key)>)} var_args
- *     The keys to type.
- * @return {!webdriver.ActionSequence} A self reference.
- * @throws {Error} If the key is not a valid modifier key.
- */
-webdriver.ActionSequence.prototype.sendKeys = function(var_args) {
-  var keys = goog.array.flatten(goog.array.slice(arguments, 0));
-  return this.scheduleKeyboardAction_('sendKeys', keys);
-};

package/lib/webdriver/builder.js

@@ -1,208 +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.
-
-goog.provide('webdriver.Builder');
-
-goog.require('goog.Uri');
-goog.require('goog.userAgent');
-goog.require('webdriver.Capabilities');
-goog.require('webdriver.FirefoxDomExecutor');
-goog.require('webdriver.WebDriver');
-goog.require('webdriver.http.CorsClient');
-goog.require('webdriver.http.Executor');
-goog.require('webdriver.http.XhrClient');
-
-
-
-/**
- * Creates new {@code webdriver.WebDriver} clients for use in a browser
- * environment. Upon instantiation, each Builder will configure itself based
- * on the following query parameters:
- * <dl>
- *   <dt>wdurl
- *   <dd>Defines the WebDriver server to send commands to. If this is a
- *       relative URL, the builder will use the standard WebDriver wire
- *       protocol and a {@link webdriver.http.XhrClient}. Otherwise, it will
- *       use a {@link webdriver.http.CorsClient}; this only works when
- *       connecting to an instance of the Java Selenium server. The server URL
- *       may be changed using {@code #usingServer}.
- *
- *   <dt>wdsid
- *   <dd>Defines the session to connect to. If omitted, will request a new
- *       session from the server.
- * </dl>
- *
- * @param {Window=} opt_window The window to extract query parameters from.
- * @constructor
- * @final
- * @struct
- */
-webdriver.Builder = function(opt_window) {
-  var win = opt_window || window;
-  var data = new goog.Uri(win.location).getQueryData();
-
-  /** @private {string} */
-  this.serverUrl_ =
-      /** @type {string} */ (data.get(webdriver.Builder.SERVER_URL_PARAM,
-      webdriver.Builder.DEFAULT_SERVER_URL)).replace(/\/$/, "");
-
-  /** @private {string} */
-  this.sessionId_ =
-      /** @type {string} */ (data.get(webdriver.Builder.SESSION_ID_PARAM));
-
-  /** @private {boolean} */
-  this.useBrowserCors_ =
-      /** @type {boolean} */ (data.containsKey(webdriver.Builder.USE_BROWSER_CORS));
-
-  /** @private {!webdriver.Capabilities} */
-  this.capabilities_ = new webdriver.Capabilities();
-};
-
-
-/**
- * Query parameter that defines which session to connect to.
- * @type {string}
- * @const
- */
-webdriver.Builder.SESSION_ID_PARAM = 'wdsid';
-
-
-/**
- * Query parameter that defines the URL of the remote server to connect to.
- * @type {string}
- * @const
- */
-webdriver.Builder.SERVER_URL_PARAM = 'wdurl';
-
-
-/**
- * The default server URL to use.
- * @type {string}
- * @const
- */
-webdriver.Builder.DEFAULT_SERVER_URL = 'http://localhost:4444/wd/hub';
-
-
-/**
- * Query parameter that defines whether browser CORS support should be used,
- * if available.
- * @type {string}
- * @const
- */
-webdriver.Builder.USE_BROWSER_CORS = 'wdcors';
-
-
-/**
- * Configures the WebDriver to use browser's CORS, if available.
- * @return {!webdriver.Builder} This Builder instance for chain calling.
- */
-webdriver.Builder.prototype.useBrowserCors = function() {
-  this.useBrowserCors_ = true;
-  return this;
-};
-
-/**
- * Configures which WebDriver server should be used for new sessions.
- * @param {string} url URL of the server to use.
- * @return {!webdriver.Builder} This Builder instance for chain calling.
- */
-webdriver.Builder.prototype.usingServer = function(url) {
-  this.serverUrl_ = url.replace(/\/$/, "");
-  return this;
-};
-
-
-/**
- * @return {string} The URL of the WebDriver server this instance is configured
- *     to use.
- */
-webdriver.Builder.prototype.getServerUrl = function() {
-  return this.serverUrl_;
-};
-
-
-/**
- * Configures the builder to create a client that will use an existing WebDriver
- * session.
- * @param {string} id The existing session ID to use.
- * @return {!webdriver.Builder} This Builder instance for chain calling.
- */
-webdriver.Builder.prototype.usingSession = function(id) {
-  this.sessionId_ = id;
-  return this;
-};
-
-
-/**
- * @return {string} The ID of the session, if any, this builder is configured
- *     to reuse.
- */
-webdriver.Builder.prototype.getSession = function() {
-  return this.sessionId_;
-};
-
-
-/**
- * Sets the desired capabilities when requesting a new session. This will
- * overwrite any previously set desired capabilities.
- * @param {!(Object|webdriver.Capabilities)} capabilities The desired
- *     capabilities for a new session.
- * @return {!webdriver.Builder} This Builder instance for chain calling.
- */
-webdriver.Builder.prototype.withCapabilities = function(capabilities) {
-  this.capabilities_ = new webdriver.Capabilities(capabilities);
-  return this;
-};
-
-
-/**
- * Builds a new {@link webdriver.WebDriver} instance using this builder's
- * current configuration.
- * @return {!webdriver.WebDriver} A new WebDriver client.
- */
-webdriver.Builder.prototype.build = function() {
-  if (goog.userAgent.GECKO && document.readyState != 'complete') {
-    throw Error('Cannot create driver instance before window.onload');
-  }
-
-  var executor;
-
-  if (webdriver.FirefoxDomExecutor.isAvailable()) {
-    executor = new webdriver.FirefoxDomExecutor();
-    return webdriver.WebDriver.createSession(executor, this.capabilities_);
-  } else {
-    var url = this.serverUrl_;
-    var client;
-    if (this.useBrowserCors_ && webdriver.http.CorsClient.isAvailable()) {
-      client = new webdriver.http.XhrClient(url);
-    } else if (url[0] == '/') {
-      var origin = window.location.origin ||
-          (window.location.protocol + '//' + window.location.host);
-      client = new webdriver.http.XhrClient(origin + url);
-    } else {
-      client = new webdriver.http.CorsClient(url);
-    }
-    executor = new webdriver.http.Executor(client);
-
-    if (this.sessionId_) {
-      return webdriver.WebDriver.attachToSession(executor, this.sessionId_);
-    } else {
-      throw new Error('Unable to create a new client for this browser. The ' +
-          'WebDriver session ID has not been defined.');
-    }
-  }
-};