selenium-webdriver 3.3.0 → 4.0.0-alpha.1

package/lib/capabilities.js

@@ -22,6 +22,7 @@
  * WebDriver session.
  */
 
+const proxy = require('./proxy');
 const Symbols = require('./symbols');
 
 
@@ -30,161 +31,190 @@ const Symbols = require('./symbols');
  * @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.
+ * Strategies for waiting for [document readiness] after a navigation
+ * event.
+ *
+ * [document readiness]: https://html.spec.whatwg.org/#current-document-readiness
+ *
  * @enum {string}
  */
-const Capability = {
+const PageLoadStrategy = {
+  /**
+   * Indicates WebDriver should not wait on the document readiness state after a
+   * navigation event.
+   */
+  NONE: 'none',
 
   /**
-   * 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}.
+   * Indicates WebDriver should wait for the document readiness state to
+   * become "interactive" after navigation.
    */
-  ACCEPT_SSL_CERTS: 'acceptSslCerts',
+  EAGER: 'eager',
+
+  /**
+   * Indicates WebDriver should wait for the document readiness state to
+   * be "complete" after navigation. This is the default page loading strategy.
+   */
+  NORMAL: 'normal'
+};
+
+
+/**
+ * Common platform names. These platforms are not explicitly defined by the
+ * WebDriver spec, however, their use is encouraged for interoperability.
+ *
+ * @enum {string}
+ * @see <https://w3c.github.io/webdriver/webdriver-spec.html>
+ */
+const Platform = {
+  LINUX: 'linux',
+  MAC: 'mac',
+  WINDOWS: 'windows'
+};
+
+
+/**
+ * Record object defining the timeouts that apply to certain WebDriver actions.
+ *
+ * @record
+ */
+function Timeouts() {}
+
+/**
+ * Defines when, in milliseconds, to interupt a script that is being
+ * {@linkplain ./webdriver.IWebDriver#executeScript evaluated}.
+ * @type {number}
+ */
+Timeouts.prototype.script;
+
+/**
+ * The timeout, in milliseconds, to apply to navigation events along with the
+ * {@link PageLoadStrategy}.
+ * @type {number}
+ */
+Timeouts.prototype.pageLoad;
+
+/**
+ * The maximimum amount of time, in milliseconds, to spend attempting to
+ * {@linkplain ./webdriver.IWebDriver#findElement locate} an element on the
+ * current page.
+ * @type {number}
+ */
+Timeouts.prototype.implicit;
 
 
+/**
+ * The possible default actions a WebDriver session can take to respond to
+ * unhandled user prompts (`window.alert()`, `window.confirm()`, and
+ * `window.prompt()`).
+ *
+ * @enum {string}
+ */
+const UserPromptHandler = {
+  /** All prompts should be silently accepted. */
+  ACCEPT: 'accept',
+  /** All prompts should be silently dismissed. */
+  DISMISS: 'dismiss',
   /**
-   * The browser name. Common browser names are defined in the {@link Browser}
-   * enum.
+   * All prompts should be automatically accepted, but an error should be
+   * returned to the next (or currently executing) WebDriver command.
    */
-  BROWSER_NAME: 'browserName',
+  ACCEPT_AND_NOTIFY: 'accept and notify',
+  /**
+   * All prompts should be automatically dismissed, but an error should be
+   * returned to the next (or currently executing) WebDriver command.
+   */
+  DISMISS_AND_NOTIFY: 'dismiss and notify',
+  /** All prompts should be left unhandled. */
+  IGNORE: 'ignore'
+};
+
+
+/**
+ * The standard WebDriver capability keys.
+ *
+ * @enum {string}
+ * @see <https://w3c.github.io/webdriver/webdriver-spec.html#capabilities>
+ */
+const Capability = {
 
   /**
-   * 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.
+   * Indicates whether a WebDriver session implicity trusts otherwise untrusted
+   * and self-signed TLS certificates during navigation.
    */
-  ELEMENT_SCROLL_BEHAVIOR: 'elementScrollBehavior',
+  ACCEPT_INSECURE_TLS_CERTS: 'acceptInsecureCerts',
 
   /**
-   * 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}.
+   * The browser name. Common browser names are defined in the
+   * {@link ./capabilities.Browser Browser} enum.
    */
-  HANDLES_ALERTS: 'handlesAlerts',
+  BROWSER_NAME: 'browserName',
+
+  /** Identifies the browser version. */
+  BROWSER_VERSION: 'browserVersion',
 
   /**
    * Key for the logging driver logging preferences.
+   * The browser name. Common browser names are defined in the
+   * {@link ./capabilities.Browser Browser} enum.
    */
   LOGGING_PREFS: 'loggingPrefs',
 
   /**
-   * Whether this session generates native events when simulating user input.
+   * Defines the session's
+   * {@linkplain ./capabilities.PageLoadStrategy page loading strategy}.
    */
-  NATIVE_EVENTS: 'nativeEvents',
+  PAGE_LOAD_STRATEGY: 'pageLoadStrategy',
 
   /**
-   * 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).
+   * Identifies the operating system of the endpoint node. Common values
+   * recognized by the most WebDriver server implementations are predefined in
+   * the {@link ./capabilities.Platform Platform} enum.
    */
-  PLATFORM: 'platform',
+  PLATFORM_NAME: 'platformName',
 
   /**
    * Describes the proxy configuration to use for a new WebDriver session.
    */
   PROXY: 'proxy',
 
-  /** Whether the driver supports changing the browser'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}.
+   * Indicates whether the remote end supports all of the window resizing and
+   * positioning commands:
+   *
+   * -  {@linkplain ./webdriver.Window#getRect Window.getRect()}
+   * -  {@linkplain ./webdriver.Window#setRect Window.setRect()}
+   * -  {@linkplain ./webdriver.Window#maximize Window.maximize()}
+   * -  {@linkplain ./webdriver.Window#minimize Window.minimize()}
+   * -  {@linkplain ./webdriver.Window#fullscreen Window.fullscreen()}
    */
-  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',
+  SET_WINDOW_RECT: 'setWindowRect',
 
   /**
-   * Defines how the driver should handle unexpected alerts. The value should
-   * be one of "accept", "dismiss", or "ignore".
+   * Describes the {@linkplain ./capabilities.Timeouts timeouts} imposed on
+   * certain session operations.
    */
-  UNEXPECTED_ALERT_BEHAVIOR: 'unexpectedAlertBehavior',
+  TIMEOUTS: 'timeouts',
 
-  /** Defines the browser version. */
-  VERSION: 'version'
+  /**
+   * Defines how a WebDriver session should
+   * {@linkplain ./capabilities.UserPromptHandler respond} to unhandled user
+   * prompts.
+   */
+  UNHANDLED_PROMPT_BEHAVIOR: 'unhandledPromptBehavior',
 };
 
 
-/**
- * Describes how a proxy should be configured for a WebDriver session.
- * @record
- */
-function ProxyConfig() {}
-
-/**
- * The proxy type. Must be one of {"manual", "pac", "system"}.
- * @type {string}
- */
-ProxyConfig.prototype.proxyType;
-
-/**
- * URL for the PAC file to use. Only used if {@link #proxyType} is "pac".
- * @type {(string|undefined)}
- */
-ProxyConfig.prototype.proxyAutoconfigUrl;
-
-/**
- * The proxy host for FTP requests. Only used if {@link #proxyType} is "manual".
- * @type {(string|undefined)}
- */
-ProxyConfig.prototype.ftpProxy;
-
-/**
- * The proxy host for HTTP requests. Only used if {@link #proxyType} is
- * "manual".
- * @type {(string|undefined)}
- */
-ProxyConfig.prototype.httpProxy;
-
-/**
- * The proxy host for HTTPS requests. Only used if {@link #proxyType} is
- * "manual".
- * @type {(string|undefined)}
- */
-ProxyConfig.prototype.sslProxy;
-
-/**
- * A comma delimited list of hosts which should bypass all proxies. Only used if
- * {@link #proxyType} is "manual".
- * @type {(string|undefined)}
- */
-ProxyConfig.prototype.noProxy;
-
-
 /**
  * Converts a generic hash object to a map.
  * @param {!Object<string, ?>} hash The hash object.
@@ -204,128 +234,93 @@ function toMap(hash) {
 /**
  * Describes a set of capabilities for a WebDriver session.
  */
-class Capabilities extends Map {
+class Capabilities {
   /**
-   * @param {(Capabilities|Map<string, ?>|Object)=} opt_other Another set of
+   * @param {(Capabilities|Map<string, ?>|Object)=} 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);
+  constructor(other = undefined) {
+    if (other instanceof Capabilities) {
+      other = other.map_;
+    } else if (other && !(other instanceof Map)) {
+      other = toMap(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');
+    /** @private @const {!Map<string, ?>} */
+    this.map_ = new Map(other);
   }
 
   /**
    * @return {!Capabilities} A basic set of capabilities for Chrome.
    */
   static chrome() {
-    return new Capabilities().set(Capability.BROWSER_NAME, Browser.CHROME);
+    return new Capabilities().setBrowserName(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 new Capabilities().setBrowserName(Browser.EDGE);
   }
 
   /**
    * @return {!Capabilities} A basic set of capabilities for Firefox.
    */
   static firefox() {
-    return new Capabilities().set(Capability.BROWSER_NAME, Browser.FIREFOX);
+    return new Capabilities().setBrowserName(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 new Capabilities().setBrowserName(Browser.INTERNET_EXPLORER);
   }
 
   /**
-   * @return {!Capabilities} A basic set of capabilities for Opera.
+   * @return {!Capabilities} A basic set of capabilities for Safari.
    */
-  static opera() {
-    return new Capabilities().
-        set(Capability.BROWSER_NAME, Browser.OPERA);
+  static safari() {
+    return new Capabilities().setBrowserName(Browser.SAFARI);
   }
 
   /**
-   * @return {!Capabilities} A basic set of capabilities for PhantomJS.
+   * @return {!Object<string, ?>} The JSON representation of this instance.
+   *     Note, the returned object may contain nested promised values.
+   * @suppress {checkTypes} Suppress [] access on a struct (state inherited from
+   *     Map).
    */
-  static phantomjs() {
-    return new Capabilities().
-        set(Capability.BROWSER_NAME, Browser.PHANTOM_JS);
+  [Symbols.serialize]() {
+    return serialize(this);
   }
 
   /**
-   * @return {!Capabilities} A basic set of capabilities for Safari.
+   * @param {string} key the parameter key to get.
+   * @return {T} the stored parameter value.
+   * @template T
    */
-  static safari() {
-    return new Capabilities().
-        set(Capability.BROWSER_NAME, Browser.SAFARI).
-        set(Capability.PLATFORM, 'MAC');
+  get(key) {
+    return this.map_.get(key);
   }
 
   /**
-   * @return {!Capabilities} A basic set of capabilities for HTMLUnit.
+   * @param {string} key the key to test.
+   * @return {boolean} whether this capability set has the specified key.
    */
-  static htmlunit() {
-    return new Capabilities().
-        set(Capability.BROWSER_NAME, Browser.HTMLUNIT);
+  has(key) {
+    return this.map_.has(key);
   }
 
   /**
-   * @return {!Capabilities} A basic set of capabilities for HTMLUnit
-   *     with enabled Javascript.
+   * @return {!Iterator<string>} an iterator of the keys set.
    */
-  static htmlunitwithjs() {
-    return new Capabilities().
-        set(Capability.BROWSER_NAME, Browser.HTMLUNIT).
-        set(Capability.SUPPORTS_JAVASCRIPT, true);
+  keys() {
+    return this.map_.keys();
   }
 
-  /**
-   * @return {!Object<string, ?>} The JSON representation of this instance.
-   *     Note, the returned object may contain nested promised values.
-   * @suppress {checkTypes} Suppress [] access on a struct (state inherited from
-   *     Map).
-   */
-  [Symbols.serialize]() {
-    return serialize(this);
+  /** @return {number} The number of capabilities set. */
+  get size() {
+    return this.map_.size;
   }
 
   /**
@@ -339,7 +334,12 @@ class Capabilities extends Map {
       throw new TypeError('no capabilities provided for merge');
     }
 
-    if (!(other instanceof Map)) {
+    let map;
+    if (other instanceof Capabilities) {
+      map = other.map_;
+    } else if (other instanceof Map) {
+      map = other;
+    } else {
       other = toMap(other);
     }
 
@@ -350,21 +350,121 @@ class Capabilities extends Map {
     return this;
   }
 
+  /**
+   * Deletes an entry from this set of capabilities.
+   *
+   * @param {string} key the capability key to delete.
+   */
+  delete(key) {
+    this.map_.delete(key);
+  }
+
   /**
    * @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);
+    this.map_.set(key, value);
     return this;
   }
 
+  /**
+   * Sets whether a WebDriver session should implicitly accept self-signed, or
+   * other untrusted TLS certificates on navigation.
+   *
+   * @param {boolean} accept whether to accept insecure certs.
+   * @return {!Capabilities} a self reference.
+   */
+  setAcceptInsecureCerts(accept) {
+    return this.set(Capability.ACCEPT_INSECURE_TLS_CERTS, accept);
+  }
+
+  /**
+   * @return {boolean} whether the session is configured to accept insecure
+   *     TLS certificates.
+   */
+  getAcceptInsecureCerts() {
+    return this.get(Capability.ACCEPT_INSECURE_TLS_CERTS);
+  }
+
+  /**
+   * Sets the name of the target browser.
+   *
+   * @param {(Browser|string)} name the browser name.
+   * @return {!Capabilities} a self reference.
+   */
+  setBrowserName(name) {
+    return this.set(Capability.BROWSER_NAME, name);
+  }
+
+  /**
+   * @return {(string|undefined)} the configured browser name, or undefined if
+   *     not set.
+   */
+  getBrowserName() {
+    return this.get(Capability.BROWSER_NAME);
+  }
+
+  /**
+   * Sets the desired version of the target browser.
+   *
+   * @param {string} version the desired version.
+   * @return {!Capabilities} a self reference.
+   */
+  setBrowserVersion(version) {
+    return this.set(Capability.BROWSER_VERSION, version);
+  }
+
+  /**
+   * @return {(string|undefined)} the configured browser version, or undefined
+   *     if not set.
+   */
+  getBrowserVersion() {
+    return this.get(Capability.BROWSER_VERSION);
+  }
+
+  /**
+   * Sets the desired page loading strategy for a new WebDriver session.
+   *
+   * @param {PageLoadStrategy} strategy the desired strategy.
+   * @return {!Capabilities} a self reference.
+   */
+  setPageLoadStrategy(strategy) {
+    return this.set(Capability.PAGE_LOAD_STRATEGY, strategy);
+  }
+
+  /**
+   * Returns the configured page load strategy.
+   *
+   * @return {(string|undefined)} the page load strategy.
+   */
+  getPageLoadStrategy() {
+    return this.get(Capability.PAGE_LOAD_STRATEGY);
+  }
+
+  /**
+   * Sets the target platform.
+   *
+   * @param {(Platform|string)} platform the target platform.
+   * @return {!Capabilities} a self reference.
+   */
+  setPlatform(platform) {
+    return this.set(Capability.PLATFORM_NAME, platform);
+  }
+
+  /**
+   * @return {(string|undefined)} the configured platform or undefined if not
+   *     set.
+   */
+  getPlatform() {
+    return this.get(Capability.PLATFORM_NAME);
+  }
+
   /**
    * Sets the logging preferences. Preferences may be specified as a
    * {@link ./logging.Preferences} instance, or as a map of log-type to
@@ -379,7 +479,7 @@ class Capabilities extends Map {
 
   /**
    * Sets the proxy configuration for this instance.
-   * @param {ProxyConfig} proxy The desired proxy configuration.
+   * @param {proxy.Config} proxy The desired proxy configuration.
    * @return {!Capabilities} A self reference.
    */
   setProxy(proxy) {
@@ -387,33 +487,32 @@ class Capabilities extends Map {
   }
 
   /**
-   * Sets whether native events should be used.
-   * @param {boolean} enabled Whether to enable native events.
-   * @return {!Capabilities} A self reference.
+   * @return {(proxy.Config|undefined)} the configured proxy settings, or
+   *     undefined if not set.
    */
-  setEnableNativeEvents(enabled) {
-    return this.set(Capability.NATIVE_EVENTS, enabled);
+  getProxy() {
+    return this.get(Capability.PROXY);
   }
 
   /**
-   * 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.
+   * Sets the default action to take with an unexpected alert before returning
+   * an error. If unspecified, WebDriver will default to
+   * {@link UserPromptHandler.DISMISS_AND_NOTIFY}.
+   *
+   * @param {?UserPromptHandler} behavior The way WebDriver should respond to
+   *     unhandled user prompts.
    * @return {!Capabilities} A self reference.
    */
-  setScrollBehavior(behavior) {
-    return this.set(Capability.ELEMENT_SCROLL_BEHAVIOR, behavior);
+  setAlertBehavior(behavior) {
+    return this.set(Capability.UNHANDLED_PROMPT_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.
+   * @return {(UserPromptHandler|undefined)} the behavior pattern for responding
+   *     to unhandled user prompts, or undefined if not set.
    */
-  setAlertBehavior(behavior) {
-    return this.set(Capability.UNEXPECTED_ALERT_BEHAVIOR, behavior);
+  getAlertBehavior() {
+    return this.get(Capability.UNHANDLED_PROMPT_BEHAVIOR);
   }
 }
 
@@ -443,8 +542,11 @@ function serialize(caps) {
 
 
 module.exports = {
-  Browser: Browser,
-  Capabilities: Capabilities,
-  Capability: Capability,
-  ProxyConfig: ProxyConfig
+  Browser,
+  Capabilities,
+  Capability,
+  PageLoadStrategy,
+  Platform,
+  Timeouts,
+  UserPromptHandler,
 };