# lib/webdriver/capabilities.js

    1// Copyright 2013 Software Freedom Conservancy2//3// Licensed under the Apache License, Version 2.0 (the "License");4// you may not use this file except in compliance with the License.5// You may obtain a copy of the License at6//7//      http://www.apache.org/licenses/LICENSE-2.08//9// Unless required by applicable law or agreed to in writing, software10// distributed under the License is distributed on an "AS IS" BASIS,11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.12// See the License for the specific language governing permissions and13// limitations under the License.1415/**16 * @fileoverview Defines the webdriver.Capabilities class.17 */1819goog.provide('webdriver.Browser');20goog.provide('webdriver.Capabilities');21goog.provide('webdriver.Capability');22goog.provide('webdriver.ProxyConfig');2324goog.require('webdriver.logging.Preferences');25262728/**29 * Recognized browser names.30 * @enum {string}31 */32webdriver.Browser = {33  ANDROID: 'android',34  CHROME: 'chrome',35  FIREFOX: 'firefox',36  INTERNET_EXPLORER: 'internet explorer',37  IPAD: 'iPad',38  IPHONE: 'iPhone',39  OPERA: 'opera',40  PHANTOM_JS: 'phantomjs',41  SAFARI: 'safari',42  HTMLUNIT: 'htmlunit'43};44454647/**48 * Describes how a proxy should be configured for a WebDriver session.49 * Proxy configuration object, as defined by the WebDriver wire protocol.50 * @typedef {(51 *     {proxyType: string}|52 *     {proxyType: string,53 *      proxyAutoconfigUrl: string}|54 *     {proxyType: string,55 *      ftpProxy: string,56 *      httpProxy: string,57 *      sslProxy: string,58 *      noProxy: string})}59 */60webdriver.ProxyConfig;61626364/**65 * Common webdriver capability keys.66 * @enum {string}67 */68webdriver.Capability = {6970  /**71   * Indicates whether a driver should accept all SSL certs by default. This72   * capability only applies when requesting a new session. To query whether73   * a driver can handle insecure SSL certs, see74   * {@link webdriver.Capability.SECURE_SSL}.75   */76  ACCEPT_SSL_CERTS: 'acceptSslCerts',777879  /**80   * The browser name. Common browser names are defined in the81   * {@link webdriver.Browser} enum.82   */83  BROWSER_NAME: 'browserName',8485  /**86   * Defines how elements should be scrolled into the viewport for interaction.87   * This capability will be set to zero (0) if elements are aligned with the88   * top of the viewport, or one (1) if aligned with the bottom. The default89   * behavior is to align with the top of the viewport.90   */91  ELEMENT_SCROLL_BEHAVIOR: 'elementScrollBehavior',9293  /**94   * Whether the driver is capable of handling modal alerts (e.g. alert,95   * confirm, prompt). To define how a driver <i>should</i> handle alerts,96   * use {@link webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR}.97   */98  HANDLES_ALERTS: 'handlesAlerts',99100  /**101   * Key for the logging driver logging preferences.102   */103  LOGGING_PREFS: 'loggingPrefs',104105  /**106   * Whether this session generates native events when simulating user input.107   */108  NATIVE_EVENTS: 'nativeEvents',109110  /**111   * Describes the platform the browser is running on. Will be one of112   * ANDROID, IOS, LINUX, MAC, UNIX, or WINDOWS. When <i>requesting</i> a113   * session, ANY may be used to indicate no platform preference (this is114   * semantically equivalent to omitting the platform capability).115   */116  PLATFORM: 'platform',117118  /**119   * Describes the proxy configuration to use for a new WebDriver session.120   */121  PROXY: 'proxy',122123  /** Whether the driver supports changing the brower's orientation. */124  ROTATABLE: 'rotatable',125126  /**127   * Whether a driver is only capable of handling secure SSL certs. To request128   * that a driver accept insecure SSL certs by default, use129   * {@link webdriver.Capability.ACCEPT_SSL_CERTS}.130   */131  SECURE_SSL: 'secureSsl',132133  /** Whether the driver supports manipulating the app cache. */134  SUPPORTS_APPLICATION_CACHE: 'applicationCacheEnabled',135136  /** Whether the driver supports locating elements with CSS selectors. */137  SUPPORTS_CSS_SELECTORS: 'cssSelectorsEnabled',138139  /** Whether the browser supports JavaScript. */140  SUPPORTS_JAVASCRIPT: 'javascriptEnabled',141142  /** Whether the driver supports controlling the browser's location info. */143  SUPPORTS_LOCATION_CONTEXT: 'locationContextEnabled',144145  /** Whether the driver supports taking screenshots. */146  TAKES_SCREENSHOT: 'takesScreenshot',147148  /**149   * Defines how the driver should handle unexpected alerts. The value should150   * be one of "accept", "dismiss", or "ignore.151   */152  UNEXPECTED_ALERT_BEHAVIOR: 'unexpectedAlertBehavior',153154  /** Defines the browser version. */155  VERSION: 'version'156};157158159160/**161 * @param {(webdriver.Capabilities|Object)=} opt_other Another set of162 *     capabilities to merge into this instance.163 * @constructor164 */165webdriver.Capabilities = function(opt_other) {166167  /** @private {!Object} */168  this.caps_ = {};169170  if (opt_other) {171    this.merge(opt_other);172  }173};174175176/**177 * @return {!webdriver.Capabilities} A basic set of capabilities for Android.178 */179webdriver.Capabilities.android = function() {180  return new webdriver.Capabilities().181      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.ANDROID).182      set(webdriver.Capability.PLATFORM, 'ANDROID');183};184185186/**187 * @return {!webdriver.Capabilities} A basic set of capabilities for Chrome.188 */189webdriver.Capabilities.chrome = function() {190  return new webdriver.Capabilities().191      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.CHROME);192};193194195/**196 * @return {!webdriver.Capabilities} A basic set of capabilities for Firefox.197 */198webdriver.Capabilities.firefox = function() {199  return new webdriver.Capabilities().200      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.FIREFOX);201};202203204/**205 * @return {!webdriver.Capabilities} A basic set of capabilities for206 *     Internet Explorer.207 */208webdriver.Capabilities.ie = function() {209  return new webdriver.Capabilities().210      set(webdriver.Capability.BROWSER_NAME,211          webdriver.Browser.INTERNET_EXPLORER).212      set(webdriver.Capability.PLATFORM, 'WINDOWS');213};214215216/**217 * @return {!webdriver.Capabilities} A basic set of capabilities for iPad.218 */219webdriver.Capabilities.ipad = function() {220  return new webdriver.Capabilities().221      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPAD).222      set(webdriver.Capability.PLATFORM, 'MAC');223};224225226/**227 * @return {!webdriver.Capabilities} A basic set of capabilities for iPhone.228 */229webdriver.Capabilities.iphone = function() {230  return new webdriver.Capabilities().231      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPHONE).232      set(webdriver.Capability.PLATFORM, 'MAC');233};234235236/**237 * @return {!webdriver.Capabilities} A basic set of capabilities for Opera.238 */239webdriver.Capabilities.opera = function() {240  return new webdriver.Capabilities().241      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.OPERA);242};243244245/**246 * @return {!webdriver.Capabilities} A basic set of capabilities for247 *     PhantomJS.248 */249webdriver.Capabilities.phantomjs = function() {250  return new webdriver.Capabilities().251      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.PHANTOM_JS);252};253254255/**256 * @return {!webdriver.Capabilities} A basic set of capabilities for Safari.257 */258webdriver.Capabilities.safari = function() {259  return new webdriver.Capabilities().260      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.SAFARI);261};262263264/**265 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit.266 */267webdriver.Capabilities.htmlunit = function() {268  return new webdriver.Capabilities().269      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT);270};271272273/**274 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit275 *     with enabled Javascript.276 */277webdriver.Capabilities.htmlunitwithjs = function() {278  return new webdriver.Capabilities().279      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT).280      set(webdriver.Capability.SUPPORTS_JAVASCRIPT, true);281};282283284/** @return {!Object} The JSON representation of this instance. */285webdriver.Capabilities.prototype.toJSON = function() {286  return this.caps_;287};288289290/**291 * Merges another set of capabilities into this instance. Any duplicates in292 * the provided set will override those already set on this instance.293 * @param {!(webdriver.Capabilities|Object)} other The capabilities to294 *     merge into this instance.295 * @return {!webdriver.Capabilities} A self reference.296 */297webdriver.Capabilities.prototype.merge = function(other) {298  var caps = other instanceof webdriver.Capabilities ?299      other.caps_ : other;300  for (var key in caps) {301    if (caps.hasOwnProperty(key)) {302      this.set(key, caps[key]);303    }304  }305  return this;306};307308309/**310 * @param {string} key The capability to set.311 * @param {*} value The capability value.  Capability values must be JSON312 *     serializable. Pass {@code null} to unset the capability.313 * @return {!webdriver.Capabilities} A self reference.314 */315webdriver.Capabilities.prototype.set = function(key, value) {316  if (goog.isDefAndNotNull(value)) {317    this.caps_[key] = value;318  } else {319    delete this.caps_[key];320  }321  return this;322};323324325/**326 * @param {string} key The capability to return.327 * @return {*} The capability with the given key, or {@code null} if it has328 *     not been set.329 */330webdriver.Capabilities.prototype.get = function(key) {331  var val = null;332  if (this.caps_.hasOwnProperty(key)) {333    val = this.caps_[key];334  }335  return goog.isDefAndNotNull(val) ? val : null;336};337338339/**340 * @param {string} key The capability to check.341 * @return {boolean} Whether the specified capability is set.342 */343webdriver.Capabilities.prototype.has = function(key) {344  return !!this.get(key);345};346347348/**349 * Sets the logging preferences. Preferences may be specified as a350 * {@link webdriver.logging.Preferences} instance, or a as a map of log-type to351 * log-level.352 * @param {!(webdriver.logging.Preferences|Object.<string, string>)} prefs The353 *     logging preferences.354 * @return {!webdriver.Capabilities} A self reference.355 */356webdriver.Capabilities.prototype.setLoggingPrefs = function(prefs) {357  return this.set(webdriver.Capability.LOGGING_PREFS, prefs);358};359360361/**362 * Sets the proxy configuration for this instance.363 * @param {webdriver.ProxyConfig} proxy The desired proxy configuration.364 * @return {!webdriver.Capabilities} A self reference.365 */366webdriver.Capabilities.prototype.setProxy = function(proxy) {367  return this.set(webdriver.Capability.PROXY, proxy);368};369370371/**372 * Sets whether native events should be used.373 * @param {boolean} enabled Whether to enable native events.374 * @return {!webdriver.Capabilities} A self reference.375 */376webdriver.Capabilities.prototype.setEnableNativeEvents = function(enabled) {377  return this.set(webdriver.Capability.NATIVE_EVENTS, enabled);378};379380381/**382 * Sets how elements should be scrolled into view for interaction.383 * @param {number} behavior The desired scroll behavior: either 0 to align with384 *     the top of the viewport or 1 to align with the bottom.385 * @return {!webdriver.Capabilities} A self reference.386 */387webdriver.Capabilities.prototype.setScrollBehavior = function(behavior) {388  return this.set(webdriver.Capability.ELEMENT_SCROLL_BEHAVIOR, behavior);389};390391392/**393 * Sets the default action to take with an unexpected alert before returning394 * an error.395 * @param {string} behavior The desired behavior; should be "accept", "dismiss",396 *     or "ignore". Defaults to "dismiss".397 * @return {!webdriver.Capabilities} A self reference.398 */399webdriver.Capabilities.prototype.setAlertBehavior = function(behavior) {400  return this.set(webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR, behavior);401};