# 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');22232425/**26 * Recognized browser names.27 * @enum {string}28 */29webdriver.Browser = {30  ANDROID: 'android',31  CHROME: 'chrome',32  FIREFOX: 'firefox',33  INTERNET_EXPLORER: 'internet explorer',34  IPAD: 'iPad',35  IPHONE: 'iPhone',36  OPERA: 'opera',37  PHANTOM_JS: 'phantomjs',38  SAFARI: 'safari',39  HTMLUNIT: 'htmlunit'40};41424344/**45 * Common webdriver capability keys.46 * @enum {string}47 */48webdriver.Capability = {4950  /**51   * Indicates whether a driver should accept all SSL certs by default. This52   * capability only applies when requesting a new session. To query whether53   * a driver can handle insecure SSL certs, see54   * {@link webdriver.Capability.SECURE_SSL}.55   */56  ACCEPT_SSL_CERTS: 'acceptSslCerts',575859  /**60   * The browser name. Common browser names are defined in the61   * {@link webdriver.Browser} enum.62   */63  BROWSER_NAME: 'browserName',6465  /**66   * Whether the driver is capable of handling modal alerts (e.g. alert,67   * confirm, prompt). To define how a driver <i>should</i> handle alerts,68   * use {@link webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR}.69   */70  HANDLES_ALERTS: 'handlesAlerts',7172  /**73   * Key for the logging driver logging preferences.74   */75  LOGGING_PREFS: 'loggingPrefs',7677  /**78   * Describes the platform the browser is running on. Will be one of79   * ANDROID, IOS, LINUX, MAC, UNIX, or WINDOWS. When <i>requesting</i> a80   * session, ANY may be used to indicate no platform preference (this is81   * semantically equivalent to omitting the platform capability).82   */83  PLATFORM: 'platform',8485  /**86   * Describes the proxy configuration to use for a new WebDriver session.87   */88  PROXY: 'proxy',8990  /** Whether the driver supports changing the brower's orientation. */91  ROTATABLE: 'rotatable',9293  /**94   * Whether a driver is only capable of handling secure SSL certs. To request95   * that a driver accept insecure SSL certs by default, use96   * {@link webdriver.Capability.ACCEPT_SSL_CERTS}.97   */98  SECURE_SSL: 'secureSsl',99100  /** Whether the driver supports manipulating the app cache. */101  SUPPORTS_APPLICATION_CACHE: 'applicationCacheEnabled',102103  /**104   * Whether the driver supports controlling the browser's internet105   * connectivity.106   */107  SUPPORTS_BROWSER_CONNECTION: 'browserConnectionEnabled',108109  /** Whether the driver supports locating elements with CSS selectors. */110  SUPPORTS_CSS_SELECTORS: 'cssSelectorsEnabled',111112  /** Whether the browser supports JavaScript. */113  SUPPORTS_JAVASCRIPT: 'javascriptEnabled',114115  /** Whether the driver supports controlling the browser's location info. */116  SUPPORTS_LOCATION_CONTEXT: 'locationContextEnabled',117118  /** Whether the driver supports taking screenshots. */119  TAKES_SCREENSHOT: 'takesScreenshot',120121  /**122   * Defines how the driver should handle unexpected alerts. The value should123   * be one of "accept", "dismiss", or "ignore.124   */125  UNEXPECTED_ALERT_BEHAVIOR: 'unexpectedAlertBehavior',126127  /** Defines the browser version. */128  VERSION: 'version'129};130131132133/**134 * @param {(webdriver.Capabilities|Object)=} opt_other Another set of135 *     capabilities to merge into this instance.136 * @constructor137 */138webdriver.Capabilities = function(opt_other) {139140  /** @private {!Object} */141  this.caps_ = {};142143  if (opt_other) {144    this.merge(opt_other);145  }146};147148149/**150 * @return {!webdriver.Capabilities} A basic set of capabilities for Android.151 */152webdriver.Capabilities.android = function() {153  return new webdriver.Capabilities().154      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.ANDROID).155      set(webdriver.Capability.PLATFORM, 'ANDROID');156};157158159/**160 * @return {!webdriver.Capabilities} A basic set of capabilities for Chrome.161 */162webdriver.Capabilities.chrome = function() {163  return new webdriver.Capabilities().164      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.CHROME);165};166167168/**169 * @return {!webdriver.Capabilities} A basic set of capabilities for Firefox.170 */171webdriver.Capabilities.firefox = function() {172  return new webdriver.Capabilities().173      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.FIREFOX);174};175176177/**178 * @return {!webdriver.Capabilities} A basic set of capabilities for179 *     Internet Explorer.180 */181webdriver.Capabilities.ie = function() {182  return new webdriver.Capabilities().183      set(webdriver.Capability.BROWSER_NAME,184          webdriver.Browser.INTERNET_EXPLORER).185      set(webdriver.Capability.PLATFORM, 'WINDOWS');186};187188189/**190 * @return {!webdriver.Capabilities} A basic set of capabilities for iPad.191 */192webdriver.Capabilities.ipad = function() {193  return new webdriver.Capabilities().194      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPAD).195      set(webdriver.Capability.PLATFORM, 'MAC');196};197198199/**200 * @return {!webdriver.Capabilities} A basic set of capabilities for iPhone.201 */202webdriver.Capabilities.iphone = function() {203  return new webdriver.Capabilities().204      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPHONE).205      set(webdriver.Capability.PLATFORM, 'MAC');206};207208209/**210 * @return {!webdriver.Capabilities} A basic set of capabilities for Opera.211 */212webdriver.Capabilities.opera = function() {213  return new webdriver.Capabilities().214      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.OPERA);215};216217218/**219 * @return {!webdriver.Capabilities} A basic set of capabilities for220 *     PhantomJS.221 */222webdriver.Capabilities.phantomjs = function() {223  return new webdriver.Capabilities().224      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.PHANTOM_JS);225};226227228/**229 * @return {!webdriver.Capabilities} A basic set of capabilities for Safari.230 */231webdriver.Capabilities.safari = function() {232  return new webdriver.Capabilities().233      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.SAFARI);234};235236237/**238 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit.239 */240webdriver.Capabilities.htmlunit = function() {241  return new webdriver.Capabilities().242      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT);243};244245246/**247 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit248 *     with enabled Javascript.249 */250webdriver.Capabilities.htmlunitwithjs = function() {251  return new webdriver.Capabilities().252      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT).253      set(webdriver.Capability.SUPPORTS_JAVASCRIPT, true);254};255256257/** @return {!Object} The JSON representation of this instance. */258webdriver.Capabilities.prototype.toJSON = function() {259  return this.caps_;260};261262263/**264 * Merges another set of capabilities into this instance. Any duplicates in265 * the provided set will override those already set on this instance.266 * @param {!(webdriver.Capabilities|Object)} other The capabilities to267 *     merge into this instance.268 * @return {!webdriver.Capabilities} A self reference.269 */270webdriver.Capabilities.prototype.merge = function(other) {271  var caps = other instanceof webdriver.Capabilities ?272      other.caps_ : other;273  for (var key in caps) {274    if (caps.hasOwnProperty(key)) {275      this.set(key, caps[key]);276    }277  }278  return this;279};280281282/**283 * @param {string} key The capability to set.284 * @param {*} value The capability value.  Capability values must be JSON285 *     serializable. Pass {@code null} to unset the capability.286 * @return {!webdriver.Capabilities} A self reference.287 */288webdriver.Capabilities.prototype.set = function(key, value) {289  if (goog.isDefAndNotNull(value)) {290    this.caps_[key] = value;291  } else {292    delete this.caps_[key];293  }294  return this;295};296297298/**299 * @param {string} key The capability to return.300 * @return {*} The capability with the given key, or {@code null} if it has301 *     not been set.302 */303webdriver.Capabilities.prototype.get = function(key) {304  var val = null;305  if (this.caps_.hasOwnProperty(key)) {306    val = this.caps_[key];307  }308  return goog.isDefAndNotNull(val) ? val : null;309};310311312/**313 * @param {string} key The capability to check.314 * @return {boolean} Whether the specified capability is set.315 */316webdriver.Capabilities.prototype.has = function(key) {317  return !!this.get(key);318};