selenium-webdriver 2.47.0 → 2.52.0

package/lib/by.js

@@ -0,0 +1,276 @@
+// 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.
+
+'use strict';
+
+/**
+ * @fileoverview Factory methods for the supported locator strategies.
+ */
+
+/**
+ * Short-hand expressions for the primary element locator strategies.
+ * For example the following two statements are equivalent:
+ *
+ *     var e1 = driver.findElement(By.id('foo'));
+ *     var e2 = driver.findElement({id: 'foo'});
+ *
+ * Care should be taken when using JavaScript minifiers (such as the
+ * Closure compiler), as locator hashes will always be parsed using
+ * the un-obfuscated properties listed.
+ *
+ * @typedef {(
+ *     {className: string}|
+ *     {css: string}|
+ *     {id: string}|
+ *     {js: string}|
+ *     {linkText: string}|
+ *     {name: string}|
+ *     {partialLinkText: string}|
+ *     {tagName: string}|
+ *     {xpath: string})}
+ */
+var ByHash;
+
+
+/**
+ * Error thrown if an invalid character is encountered while escaping a CSS
+ * identifier.
+ * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ */
+class InvalidCharacterError extends Error {
+  constructor() {
+    super();
+    this.name = this.constructor.name;
+  }
+}
+
+
+/**
+ * Escapes a CSS string.
+ * @param {string} css the string to escape.
+ * @return {string} the escaped string.
+ * @throws {TypeError} if the input value is not a string.
+ * @throws {InvalidCharacterError} if the string contains an invalid character.
+ * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ */
+function escapeCss(css) {
+  if (typeof css !== 'string') {
+    throw new TypeError('input must be a string');
+  }
+  let ret = '';
+  const n = css.length;
+  for (let i = 0; i  < n; i++) {
+    const c = css.charCodeAt(i);
+    if (c == 0x0) {
+      throw new InvalidCharacterError();
+    }
+
+    if ((c >= 0x0001 && c <= 0x001F)
+        || c == 0x007F
+        || (i == 0 && c >= 0x0030 && c <= 0x0039)
+        || (i == 1 && c >= 0x0030 && c <= 0x0039
+            && css.charCodeAt(0) == 0x002D)) {
+      ret += '\\' + c.toString(16);
+      continue;
+    }
+
+    if (i == 0 && c == 0x002D && n == 1) {
+      ret += '\\' + css.charAt(i);
+      continue;
+    }
+
+    if (c >= 0x0080
+        || c == 0x002D                      // -
+        || c == 0x005F                      // _
+        || (c >= 0x0030 && c <= 0x0039)     // [0-9]
+        || (c >= 0x0041 && c <= 0x005A)     // [A-Z]
+        || (c >= 0x0061 && c <= 0x007A)) {  // [a-z]
+      ret += css.charAt(i);
+      continue;
+    }
+
+    ret += '\\' + css.charAt(i);
+  }
+  return ret;
+}
+
+
+/**
+ * Describes a mechanism for locating an element on the page.
+ * @final
+ */
+class By {
+  /**
+   * @param {string} using the name of the location strategy to use.
+   * @param {string} value the value to search for.
+   */
+  constructor(using, value) {
+    /** @type {string} */
+    this.using = using;
+
+    /** @type {string} */
+    this.value = value;
+  }
+
+  /**
+   * Locates elements that have a specific class name.
+   *
+   * @param {string} name The class name to search for.
+   * @return {!By} The new locator.
+   * @see http://www.w3.org/TR/2011/WD-html5-20110525/elements.html#classes
+   * @see http://www.w3.org/TR/CSS2/selector.html#class-html
+   */
+  static className(name) {
+    let names = name.split(/\s+/g)
+        .filter(s => s.length > 0)
+        .map(s => escapeCss(s));
+    return By.css('.' + names.join('.'));
+  }
+
+  /**
+   * Locates elements using a CSS selector.
+   *
+   * @param {string} selector The CSS selector to use.
+   * @return {!By} The new locator.
+   * @see http://www.w3.org/TR/CSS2/selector.html
+   */
+  static css(selector) {
+    return new By('css selector', selector);
+  }
+
+  /**
+   * Locates eleemnts by the ID attribute. This locator uses the CSS selector
+   * `*[id="$ID"]`, _not_ `document.getElementById`.
+   *
+   * @param {string} id The ID to search for.
+   * @return {!By} The new locator.
+   */
+  static id(id) {
+    return By.css('*[id="' + escapeCss(id) + '"]');
+  }
+
+  /**
+   * Locates link elements whose
+   * {@linkplain webdriver.WebElement#getText visible text} matches the given
+   * string.
+   *
+   * @param {string} text The link text to search for.
+   * @return {!By} The new locator.
+   */
+  static linkText(text) {
+    return new By('link text', text);
+  }
+
+  /**
+   * Locates an elements by evaluating a
+   * {@linkplain webdriver.WebDriver#executeScript JavaScript expression}.
+   * The result of this expression must be an element or list of elements.
+   *
+   * @param {!(string|Function)} script The script to execute.
+   * @param {...*} var_args The arguments to pass to the script.
+   * @return {function(!./webdriver.WebDriver): !./promise.Promise}
+   *     A new JavaScript-based locator function.
+   */
+  static js(script, var_args) {
+    let args = Array.prototype.slice.call(arguments, 0);
+    return function(driver) {
+      return driver.executeScript.apply(driver, args);
+    };
+  }
+
+  /**
+   * Locates elements whose `name` attribute has the given value.
+   *
+   * @param {string} name The name attribute to search for.
+   * @return {!By} The new locator.
+   */
+  static name(name) {
+    return By.css('*[name="' + escapeCss(name) + '"]');
+  }
+
+  /**
+   * Locates link elements whose
+   * {@linkplain webdriver.WebElement#getText visible text} contains the given
+   * substring.
+   *
+   * @param {string} text The substring to check for in a link's visible text.
+   * @return {!By} The new locator.
+   */
+  static partialLinkText(text) {
+    return new By('partial link text', text);
+  }
+
+  /**
+   * Locates elements with a given tag name.
+   *
+   * @param {string} name The tag name to search for.
+   * @return {!By} The new locator.
+   * @deprecated Use {@link By.css() By.css(tagName)} instead.
+   */
+  static tagName(name) {
+    return By.css(name);
+  }
+
+  /**
+   * Locates elements matching a XPath selector. Care should be taken when
+   * using an XPath selector with a {@link webdriver.WebElement} as WebDriver
+   * will respect the context in the specified in the selector. For example,
+   * given the selector `//div`, WebDriver will search from the document root
+   * regardless of whether the locator was used with a WebElement.
+   *
+   * @param {string} xpath The XPath selector to use.
+   * @return {!By} The new locator.
+   * @see http://www.w3.org/TR/xpath/
+   */
+  static xpath(xpath) {
+    return new By('xpath', xpath);
+  }
+
+  /** @override */
+  toString() {
+    // The static By.name() overrides this.constructor.name.  Shame...
+    return `By(${this.using}, ${this.value})`;
+  }
+}
+
+
+/**
+ * Checks if a value is a valid locator.
+ * @param {!(By|Function|ByHash)} locator The value to check.
+ * @return {!(By|Function)} The valid locator.
+ * @throws {TypeError} If the given value does not define a valid locator
+ *     strategy.
+ */
+function check(locator) {
+  if (locator instanceof By || typeof locator === 'function') {
+    return locator;
+  }
+  for (let key in locator) {
+    if (locator.hasOwnProperty(key) && By.hasOwnProperty(key)) {
+      return By[key](locator[key]);
+    }
+  }
+  throw new TypeError('Invalid locator');
+}
+
+
+
+// PUBLIC API
+
+
+exports.By = By;
+exports.checkedLocator = check;

package/lib/capabilities.js

@@ -0,0 +1,404 @@
+// 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.
+
+'use strict';
+
+/**
+ * @fileoverview Defines types related to describing the capabilities of a
+ * WebDriver session.
+ */
+
+const Symbols = require('./symbols');
+
+
+/**
+ * Recognized browser names.
+ * @enum {string}
+ */
+const Browser = {
+  ANDROID: 'android',
+  CHROME: 'chrome',
+  EDGE: 'MicrosoftEdge',
+  FIREFOX: 'firefox',
+  IE: 'internet explorer',
+  INTERNET_EXPLORER: 'internet explorer',
+  IPAD: 'iPad',
+  IPHONE: 'iPhone',
+  OPERA: 'opera',
+  PHANTOM_JS: 'phantomjs',
+  SAFARI: 'safari',
+  HTMLUNIT: 'htmlunit'
+};
+
+
+/**
+ * Common Capability keys.
+ * @enum {string}
+ */
+const Capability = {
+
+  /**
+   * Indicates whether a driver should accept all SSL certs by default. This
+   * capability only applies when requesting a new session. To query whether
+   * a driver can handle insecure SSL certs, see {@link #SECURE_SSL}.
+   */
+  ACCEPT_SSL_CERTS: 'acceptSslCerts',
+
+
+  /**
+   * The browser name. Common browser names are defined in the {@link Browser}
+   * enum.
+   */
+  BROWSER_NAME: 'browserName',
+
+  /**
+   * Defines how elements should be scrolled into the viewport for interaction.
+   * This capability will be set to zero (0) if elements are aligned with the
+   * top of the viewport, or one (1) if aligned with the bottom. The default
+   * behavior is to align with the top of the viewport.
+   */
+  ELEMENT_SCROLL_BEHAVIOR: 'elementScrollBehavior',
+
+  /**
+   * Whether the driver is capable of handling modal alerts (e.g. alert,
+   * confirm, prompt). To define how a driver <i>should</i> handle alerts,
+   * use {@link #UNEXPECTED_ALERT_BEHAVIOR}.
+   */
+  HANDLES_ALERTS: 'handlesAlerts',
+
+  /**
+   * Key for the logging driver logging preferences.
+   */
+  LOGGING_PREFS: 'loggingPrefs',
+
+  /**
+   * Whether this session generates native events when simulating user input.
+   */
+  NATIVE_EVENTS: 'nativeEvents',
+
+  /**
+   * Describes the platform the browser is running on. Will be one of
+   * ANDROID, IOS, LINUX, MAC, UNIX, or WINDOWS. When <i>requesting</i> a
+   * session, ANY may be used to indicate no platform preference (this is
+   * semantically equivalent to omitting the platform capability).
+   */
+  PLATFORM: 'platform',
+
+  /**
+   * Describes the proxy configuration to use for a new WebDriver session.
+   */
+  PROXY: 'proxy',
+
+  /** Whether the driver supports changing the brower's orientation. */
+  ROTATABLE: 'rotatable',
+
+  /**
+   * Whether a driver is only capable of handling secure SSL certs. To request
+   * that a driver accept insecure SSL certs by default, use
+   * {@link #ACCEPT_SSL_CERTS}.
+   */
+  SECURE_SSL: 'secureSsl',
+
+  /** Whether the driver supports manipulating the app cache. */
+  SUPPORTS_APPLICATION_CACHE: 'applicationCacheEnabled',
+
+  /** Whether the driver supports locating elements with CSS selectors. */
+  SUPPORTS_CSS_SELECTORS: 'cssSelectorsEnabled',
+
+  /** Whether the browser supports JavaScript. */
+  SUPPORTS_JAVASCRIPT: 'javascriptEnabled',
+
+  /** Whether the driver supports controlling the browser's location info. */
+  SUPPORTS_LOCATION_CONTEXT: 'locationContextEnabled',
+
+  /** Whether the driver supports taking screenshots. */
+  TAKES_SCREENSHOT: 'takesScreenshot',
+
+  /**
+   * Defines how the driver should handle unexpected alerts. The value should
+   * be one of "accept", "dismiss", or "ignore.
+   */
+  UNEXPECTED_ALERT_BEHAVIOR: 'unexpectedAlertBehavior',
+
+  /** Defines the browser version. */
+  VERSION: 'version'
+};
+
+
+/**
+ * Describes how a proxy should be configured for a WebDriver session.
+ * Proxy configuration object, as defined by the WebDriver wire protocol.
+ * @typedef {(
+ *     {proxyType: string}|
+ *     {proxyType: string,
+ *      proxyAutoconfigUrl: string}|
+ *     {proxyType: string,
+ *      ftpProxy: string,
+ *      httpProxy: string,
+ *      sslProxy: string,
+ *      noProxy: string})}
+ */
+var ProxyConfig;
+
+
+/**
+ * Converts a generic hash object to a map.
+ * @param {!Object<string, ?>} hash The hash object.
+ * @return {!Map<string, ?>} The converted map.
+ */
+function toMap(hash) {
+  let m = new Map;
+  for (let key in hash) {
+    if (hash.hasOwnProperty(key)) {
+      m.set(key, hash[key]);
+    }
+  }
+  return m;
+}
+
+
+/**
+ * Describes a set of capabilities for a WebDriver session.
+ */
+class Capabilities extends Map {
+  /**
+   * @param {(Capabilities|Map<string, ?>|Object)=} opt_other Another set of
+   *     capabilities to initialize this instance from.
+   */
+  constructor(opt_other) {
+    if (opt_other && !(opt_other instanceof Map)) {
+      opt_other = toMap(opt_other);
+    }
+    super(opt_other);
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for Android.
+   */
+  static android() {
+    return new Capabilities()
+        .set(Capability.BROWSER_NAME, Browser.ANDROID)
+        .set(Capability.PLATFORM, 'ANDROID');
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for Chrome.
+   */
+  static chrome() {
+    return new Capabilities().set(Capability.BROWSER_NAME, Browser.CHROME);
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for Microsoft Edge.
+   */
+  static edge() {
+    return new Capabilities()
+        .set(Capability.BROWSER_NAME, Browser.EDGE)
+        .set(Capability.PLATFORM, 'WINDOWS');
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for Firefox.
+   */
+  static firefox() {
+    return new Capabilities().set(Capability.BROWSER_NAME, Browser.FIREFOX);
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for Internet Explorer.
+   */
+  static ie() {
+    return new Capabilities().
+        set(Capability.BROWSER_NAME, Browser.INTERNET_EXPLORER).
+        set(Capability.PLATFORM, 'WINDOWS');
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for iPad.
+   */
+  static ipad() {
+    return new Capabilities().
+        set(Capability.BROWSER_NAME, Browser.IPAD).
+        set(Capability.PLATFORM, 'MAC');
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for iPhone.
+   */
+  static iphone() {
+    return new Capabilities().
+        set(Capability.BROWSER_NAME, Browser.IPHONE).
+        set(Capability.PLATFORM, 'MAC');
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for Opera.
+   */
+  static opera() {
+    return new Capabilities().
+        set(Capability.BROWSER_NAME, Browser.OPERA);
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for PhantomJS.
+   */
+  static phantomjs() {
+    return new Capabilities().
+        set(Capability.BROWSER_NAME, Browser.PHANTOM_JS);
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for Safari.
+   */
+  static safari() {
+    return new Capabilities().
+        set(Capability.BROWSER_NAME, Browser.SAFARI).
+        set(Capability.PLATFORM, 'MAC');
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for HTMLUnit.
+   */
+  static htmlunit() {
+    return new Capabilities().
+        set(Capability.BROWSER_NAME, Browser.HTMLUNIT);
+  }
+
+  /**
+   * @return {!Capabilities} A basic set of capabilities for HTMLUnit
+   *     with enabled Javascript.
+   */
+  static htmlunitwithjs() {
+    return new Capabilities().
+        set(Capability.BROWSER_NAME, Browser.HTMLUNIT).
+        set(Capability.SUPPORTS_JAVASCRIPT, true);
+  }
+
+  /**
+   * @return {!Object<string, ?>} The JSON representation of this instance.
+   *     Note, the returned object may contain nested promised values.
+   */
+  [Symbols.serialize]() {
+    let ret = {};
+    for (let key of this.keys()) {
+      let cap = this.get(key);
+      if (cap) {
+        ret[key] = cap;
+      }
+    }
+    return ret;
+  }
+
+  /**
+   * Merges another set of capabilities into this instance.
+   * @param {!(Capabilities|Map<String, ?>|Object<string, ?>)} other The other
+   *     set of capabilities to merge.
+   * @return {!Capabilities} A self reference.
+   */
+  merge(other) {
+    if (!other) {
+      throw new TypeError('no capabilities provided for merge');
+    }
+
+    if (!(other instanceof Map)) {
+      other = toMap(other);
+    }
+
+    for (let key of other.keys()) {
+      this.set(key, other.get(key));
+    }
+
+    return this;
+  }
+
+  /**
+   * @param {string} key The capability key.
+   * @param {*} value The capability value.
+   * @return {!Capabilities} A self reference.
+   * @throws {TypeError} If the `key` is not a string.
+   * @override
+   */
+  set(key, value) {
+    if (typeof key !== 'string') {
+      throw new TypeError('Capability keys must be strings: ' + typeof key);
+    }
+    super.set(key, value);
+    return this;
+  }
+
+  /**
+   * Sets the logging preferences. Preferences may be specified as a
+   * {@link ./logging.Preferences} instance, or a as a map of log-type to
+   * log-level.
+   * @param {!(./logging.Preferences|Object<string>)} prefs The logging
+   *     preferences.
+   * @return {!Capabilities} A self reference.
+   */
+  setLoggingPrefs(prefs) {
+    return this.set(Capability.LOGGING_PREFS, prefs);
+  }
+
+  /**
+   * Sets the proxy configuration for this instance.
+   * @param {ProxyConfig} proxy The desired proxy configuration.
+   * @return {!Capabilities} A self reference.
+   */
+  setProxy(proxy) {
+    return this.set(Capability.PROXY, proxy);
+  }
+
+  /**
+   * Sets whether native events should be used.
+   * @param {boolean} enabled Whether to enable native events.
+   * @return {!Capabilities} A self reference.
+   */
+  setEnableNativeEvents(enabled) {
+    return this.set(Capability.NATIVE_EVENTS, enabled);
+  }
+
+  /**
+   * Sets how elements should be scrolled into view for interaction.
+   * @param {number} behavior The desired scroll behavior: either 0 to align
+   *     with the top of the viewport or 1 to align with the bottom.
+   * @return {!Capabilities} A self reference.
+   */
+  setScrollBehavior(behavior) {
+    return this.set(Capability.ELEMENT_SCROLL_BEHAVIOR, behavior);
+  }
+
+  /**
+   * Sets the default action to take with an unexpected alert before returning
+   * an error.
+   * @param {string} behavior The desired behavior; should be "accept",
+   *     "dismiss", or "ignore". Defaults to "dismiss".
+   * @return {!Capabilities} A self reference.
+   */
+  setAlertBehavior(behavior) {
+    return this.set(Capability.UNEXPECTED_ALERT_BEHAVIOR, behavior);
+  }
+}
+
+
+// PUBLIC API
+
+
+exports.Browser = Browser;
+exports.Capabilities = Capabilities;
+exports.Capability = Capability;
+
+/** @typedef {ProxyConfig} */
+exports.ProxyConfig = ProxyConfig;