selenium-webdriver 0.0.1

data/common/src/js/extension/README

@@ -0,0 +1,2 @@
+This directory contains Javascript files that are used in both the Chrome and
+Firefox extensions.

data/common/src/js/extension/dommessenger.js

@@ -0,0 +1,152 @@
+/*
+Copyright 2007-2009 WebDriver committers
+Copyright 2007-2009 Google Inc.
+Portions copyright 2007 ThoughtWorks, Inc
+
+Licensed 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.
+*/
+
+/**
+ * @fileoverview Messenger service used to communicate with the current web
+ * page through custom DOM events.
+ *
+ * <p>The DomMessenger will listen for {@code webdriverCommand} events on the
+ * document. The event target should be a node whose {@code command} attribute
+ * is a JSON string with the command to execute.
+ *
+ * <p>Once the command has been executed, the response will be stored as a JSON
+ * string in the {@code response} attribute of the node that dispatched the
+ * original {@code webdriverCommand} event. The DomMessenger will then dispatch
+ * a {@code webdriverResponse} event on that node to notify the page that a
+ * response is ready.
+ * 
+ * @author jmleyba@gmail.com (Jason Leyba)
+ */
+
+
+/**
+ * The DomMessenger is used to communicate with the current webpage through
+ * custom events fired on the DOM.
+ *
+ * @param { {execute: function(string, function(string))} } commandProcessor The
+ *     object to send commands to for execution. The object should have a single
+ *     method, {@code execute}, that takes two arguments: the command to execute
+ *     as a JSON string, and a callback for the command response (specified as a
+ *     JSON string).
+ * @constructor
+ */
+var DomMessenger = function(commandProcessor) {
+
+  /**
+   * The object to use as a command processor.
+   * @type { {execute: function(string, function(string))} }
+   * @private
+   */
+  this.commandProcessor_ = commandProcessor;
+
+  var self = this;  // TODO(jmleyba): bind
+
+  /**
+   * EventListener for {@code COMMAND_EVENT}s.
+   * @type {function(Event)}
+   * @private
+   */
+  this.commandEventListener_ = function(e) {
+    self.onCommand(e);
+  };
+};
+
+
+/**
+ * Attributes used to pass information between the extension and the current
+ * web page.
+ * @enum {string}
+ */
+DomMessenger.Attribute = {
+  COMMAND: 'command',
+  RESPONSE: 'response'
+};
+
+
+/**
+ * Custom event types used to signal a new message either to or from the current
+ * web page.
+ * @enum {string}
+ */
+DomMessenger.EventType = {
+  COMMAND: 'webdriverCommand',
+  RESPONSE: 'webdriverResponse'
+};
+
+
+/**
+ * Called when a page loads to 
+ * Called when a page loads so an element can be injected for communicating with
+ * the web page.
+ */
+DomMessenger.prototype.onPageLoad = function(e) {
+  // Annotate the documentElement to signal to the client that webdriver is
+  // installed.
+  var doc = e.originalTarget || e.target;
+  doc.documentElement.setAttribute('webdriver', true);
+  doc.addEventListener(
+      DomMessenger.EventType.COMMAND, this.commandEventListener_, true);
+};
+
+
+/**
+ * Called when a page unloads; removes the command event listener.
+ * @param {Event} e The unload event, whose target is the document that was
+ *    unloaded.
+ */
+DomMessenger.prototype.onPageUnload = function(e) {
+  var doc = e.originalTarget || e.target;
+  doc.removeEventListener(
+      DomMessenger.EventType.COMMAND, this.commandEventListener_, true);
+};
+
+
+/**
+ * Handles {@code COMMAND_EVENT}s. The command should be stored as a JSON string
+ * in the {@code COMMAND_ATTRIBUTE}.
+ * @param {Event} e The command event.
+ */
+DomMessenger.prototype.onCommand = function(e) {
+  var client = e.target;
+  var command = client.getAttribute(DomMessenger.Attribute.COMMAND);
+
+  if (!command) {
+    throw Error('No command specified');
+  }
+
+  var self = this;  // TODO(jmleyba): bind
+  this.commandProcessor_.execute(command, function(response) {
+    self.dispatchResponse(client, response);
+  });
+};
+
+
+/**
+ * Dispatches a {@code RESPONSE_EVENT} to notify the appropriate page that a
+ * command it gave completed execution.
+ * @param {Node} client The DOM node that issued the command this response is
+ *     for.
+ * @param {string} response Response to a command as a JSON string.
+ */
+DomMessenger.prototype.dispatchResponse = function(client, response) {
+  client.setAttribute(DomMessenger.Attribute.RESPONSE, response);
+  var evt = client.ownerDocument.createEvent('Event');
+  evt.initEvent(DomMessenger.EventType.RESPONSE,
+      /*canBubble=*/true, /*cancellable=*/true);
+  client.dispatchEvent(evt);
+};

data/common/src/js/factory.js

@@ -0,0 +1,55 @@
+/** @license
+Copyright 2007-2009 WebDriver committers
+Copyright 2007-2009 Google Inc.
+
+Licensed 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.
+*/
+
+/**
+ * @fileoverview Provides factory methods for creating new instances of
+ * {@code webdriver.WebDriver}.
+ * @author jmleyba@gmail.com (Jason Leyba)
+ */
+
+goog.provide('webdriver.factory');
+
+goog.require('goog.userAgent');
+goog.require('webdriver.LocalCommandProcessor');
+goog.require('webdriver.WebDriver');
+
+
+/**
+ * Creates a new {@code webdriver.WebDriver} instance that uses an
+ * {@code webdriver.AbstractCommandProcessor}. This driver will only be able to
+ * perform the most basic of commands: sleeping and calling user defined
+ * functions.
+ * @return {webdriver.WebDriver} A new WebDriver instance.
+ */
+webdriver.factory.createAbstractDriver = function() {
+  return new webdriver.WebDriver(new webdriver.AbstractCommandProcessor());
+};
+
+
+/**
+ * Creates a new {@code webdriver.WebDriver} instance that uses a
+ * CommandProcessor directly accessible to the current JavaScript engine.
+ * Currently, only Firefox is supported, but IE and Google Chrome support is
+ * planned.
+ * TODO(jmleyba): Add support for Internet Explorer and Goolge Chrome.
+ * @return {webdriver.WebDriver} A new WebDriver instance.
+ * @throws If called from a JavaScript engine that does not have support for a
+ *     local CommandProcessor.
+ */
+webdriver.factory.createLocalWebDriver = function() {
+  return new webdriver.WebDriver(new webdriver.LocalCommandProcessor());
+};

data/common/src/js/future.js

@@ -0,0 +1,118 @@
+/** @license
+Copyright 2007-2009 WebDriver committers
+Copyright 2007-2009 Google Inc.
+
+Licensed 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.
+*/
+
+/**
+ * @fileoverview Defines a class for representing the result of an asynchronous
+ * {@code webdriver.Command}.
+ * @author jmleyba@gmail.com (Jason Leyba)
+ */
+
+goog.provide('webdriver.Future');
+
+goog.require('goog.events.EventType');
+goog.require('goog.events.EventTarget');
+
+
+/**
+ * Represents the result of an asynchronous {@code webdriver.Command}. Methods
+ * are provided to check if the result has been set and to retrieve the result.
+ * <p/>
+ * This instance will dispatch a {@code goog.events.EventType.CHANGE} event when
+ * its value is set. An {@code Error} will be thrown if {@code #getValue()} is
+ * called before the value has been set.
+ * @param {webdriver.WebDriver} driver The WebDriver instance that will
+ *     eventually set this instance's value.
+ * @constructor
+ * @extends {goog.events.EventTarget}
+ */
+webdriver.Future = function(driver) {
+  goog.events.EventTarget.call(this);
+
+  /**
+   * The WebDriver that will eventaully set this instance's value.
+   * @type {webdriver.WebDriver}
+   * @private
+   */
+  this.driver_ = driver;
+
+  /**
+   * The value of this Future.
+   * @type {*}
+   * @private
+   */
+  this.value_ = webdriver.Future.NOT_SET_;
+};
+goog.inherits(webdriver.Future,  goog.events.EventTarget);
+
+
+/**
+ * A special place-holder value used to represent that the result for a future
+ * has not been computed yet.
+ * @type {Object}
+ * @private
+ */
+webdriver.Future.NOT_SET_ = {};
+
+
+/**
+ * @return {*} The value of this Future.
+ * @throws If the value has not been set yet.
+ */
+webdriver.Future.prototype.getValue = function() {
+  if (this.value_ === webdriver.Future.NOT_SET_) {
+    throw new Error('Value has not been set yet');
+  }
+  return this.value_;
+};
+
+
+/**
+ * @return {webdriver.WebDriver} The WebDriver that set/will set this Future's
+ *     value.
+ */
+webdriver.Future.prototype.getDriver = function() {
+  return this.driver_;
+};
+
+
+/**
+ * Sets the value of this Future. Dispatches a
+ * {@code goog.events.EventType.CHANGE} event.
+ * @param {*} value The new value.
+ */
+webdriver.Future.prototype.setValue = function(value) {
+  this.value_ = value;
+  this.dispatchEvent(goog.events.EventType.CHANGE);
+};
+
+
+/**
+ * Sets the value of this future from the value of a Response object.
+ * @param {webdriver.Response} response The webdriver.Response to set the value
+ *     from.
+ */
+webdriver.Future.prototype.setValueFromResponse = function(response) {
+  this.setValue(response.value);
+};
+
+
+/**
+ * @return {boolean} Whether this future has had its value set.
+ */
+webdriver.Future.prototype.isSet = function() {
+  return this.value_ !== webdriver.Future.NOT_SET_;
+};

data/common/src/js/key.js

@@ -0,0 +1,117 @@
+/** @license
+Copyright 2007-2009 WebDriver committers
+Copyright 2007-2009 Google Inc.
+
+Licensed 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.Key');
+
+goog.require('goog.array');
+
+
+/**
+ * Representations of pressable keys that aren't text.  These are stored in
+ * the Unicode PUA (Private Use Area) code points, 0xE000-0xF8FF.  Refer to
+ * http://www.google.com.au/search?&q=unicode+pua&btnG=Search
+ * @enum {string}
+ */
+webdriver.Key = {
+  NULL:         '\uE000',
+  CANCEL:       '\uE001',  // ^break
+  HELP:         '\uE002',
+  BACK_SPACE:   '\uE003',
+  TAB:          '\uE004',
+  CLEAR:        '\uE005',
+  RETURN:       '\uE006',
+  ENTER:        '\uE007',
+  SHIFT:        '\uE008',
+  LEFT_SHIFT:   '\uE008', // alias
+  CONTROL:      '\uE009',
+  LEFT_CONTROL: '\uE009', // alias
+  ALT:          '\uE00A',
+  LEFT_ALT:     '\uE00A', // alias
+  PAUSE:        '\uE00B',
+  ESCAPE:       '\uE00C',
+  SPACE:        '\uE00D',
+  PAGE_UP:      '\uE00E',
+  PAGE_DOWN:    '\uE00F',
+  END:          '\uE010',
+  HOME:         '\uE011',
+  LEFT:         '\uE012',
+  ARROW_LEFT:   '\uE012', // alias
+  UP:           '\uE013',
+  ARROW_UP:     '\uE013', // alias
+  RIGHT:        '\uE014',
+  ARROW_RIGHT:  '\uE014', // alias
+  DOWN:         '\uE015',
+  ARROW_DOWN:   '\uE015', // alias
+  INSERT:       '\uE016',
+  DELETE:       '\uE017',
+  SEMICOLON:    '\uE018',
+  EQUALS:       '\uE019',
+
+  NUMPAD0:      '\uE01A',  // number pad keys
+  NUMPAD1:      '\uE01B',
+  NUMPAD2:      '\uE01C',
+  NUMPAD3:      '\uE01D',
+  NUMPAD4:      '\uE01E',
+  NUMPAD5:      '\uE01F',
+  NUMPAD6:      '\uE020',
+  NUMPAD7:      '\uE021',
+  NUMPAD8:      '\uE022',
+  NUMPAD9:      '\uE023',
+  MULTIPLY:     '\uE024',
+  ADD:          '\uE025',
+  SEPARATOR:    '\uE026',
+  SUBTRACT:     '\uE027',
+  DECIMAL:      '\uE028',
+  DIVIDE:       '\uE029',
+
+  F1:           '\uE031',  // function keys
+  F2:           '\uE032',
+  F3:           '\uE033',
+  F4:           '\uE034',
+  F5:           '\uE035',
+  F6:           '\uE036',
+  F7:           '\uE037',
+  F8:           '\uE038',
+  F9:           '\uE039',
+  F10:          '\uE03A',
+  F11:          '\uE03B',
+  F12:          '\uE03C',
+
+  COMMAND:      '\uE03D',  // Apple command key
+  META:         '\uE03D'   // alias for Windows key
+};
+
+/**
+* Simulate pressing many keys at once in a "chord". Takes a sequence of
+* Keys.XXXX or strings; appends each of the values to a string, and adds the
+* chord termination key (Keys.NULL) and returns the resultant string.
+*
+* Note: when the low-level webdriver key handlers see Keys.NULL, active
+* modifier keys (CTRL/ALT/SHIFT/etc) release via a keyup event.
+*
+* @param {string|webdriver.Key} var_args The key sequence to concatenate.
+* @see http://code.google.com/p/webdriver/issues/detail?id=79
+*/
+webdriver.Key.chord = function(var_args) {
+  var sequence = goog.array.reduce(
+      goog.array.slice(arguments, 0),
+      function(str, key) {
+        return str + key;
+      }, '');
+  sequence += webdriver.Key.NULL;
+  return sequence;
+};

data/common/src/js/localcommandprocessor.js

@@ -0,0 +1,181 @@
+/** @license
+Copyright 2007-2009 WebDriver committers
+Copyright 2007-2009 Google Inc.
+
+Licensed 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.
+*/
+
+/**
+ * @fileoverview Defines a command processor that uses a browser
+ * extension/plugin object available to the Javascript on the page.
+ * @author jmleyba@gmail.com (Jason Leyba)
+ */
+
+goog.provide('webdriver.LocalCommandProcessor');
+
+goog.require('goog.array');
+goog.require('goog.dom');
+goog.require('goog.events');
+goog.require('goog.json');
+goog.require('goog.object');
+goog.require('webdriver.AbstractCommandProcessor');
+goog.require('webdriver.CommandName');
+goog.require('webdriver.Context');
+goog.require('webdriver.Response');
+
+
+/**
+ * Command processor that uses a browser extension/plugin exposed to the page
+ * for executing WebDriver commands.
+ * @param {goog.dom.DomHelper} opt_dom The DomHelper for this instance to use;
+ *     defaults to a DomHelper for the current document.
+ * @constructor
+ * @extends {webdriver.AbstractCommandProcessor}
+ */
+webdriver.LocalCommandProcessor = function(opt_dom) {
+  webdriver.AbstractCommandProcessor.call(this);
+  // TODO(jmleyba): IE, Chrome, et al. support
+
+  /**
+   * The DomHelper for this instance to use.
+   * @type {goog.dom.DomHelper}
+   * @private
+   */
+  this.dom_ = opt_dom || goog.dom.getDomHelper();
+
+  /**
+   * The element to use for communicating with the extension.
+   * @type {Element}
+   * @private
+   */
+  this.documentElement_ = this.dom_.getDocument().documentElement;
+
+  // Verify the extension is installed by checking for the webdriver attribute
+  // on the documentElement.
+  var webdriverAttribute = this.documentElement_.getAttribute('webdriver');
+  if (!webdriverAttribute) {
+    throw Error(
+        'The current browser does not support a LocalCommandProcessor');
+  }
+};
+goog.inherits(webdriver.LocalCommandProcessor,
+              webdriver.AbstractCommandProcessor);
+
+
+/**
+ * The custom event types used to communicate with the browser extension.
+ * @enum {string}
+ */
+webdriver.LocalCommandProcessor.EventType_ = {
+  COMMAND: 'webdriverCommand',
+  RESPONSE: 'webdriverResponse'
+};
+
+
+/**
+ * The attributes used to store information passed to the browser extension.
+ * @enum {string}
+ */
+webdriver.LocalCommandProcessor.MessageAttribute_ = {
+  COMMAND: 'command',
+  RESPONSE: 'response'
+};
+
+
+/**
+ * @override
+ */
+webdriver.LocalCommandProcessor.prototype.dispose = function() {
+  goog.events.removeAll(this.documentElement_,
+      webdriver.LocalCommandProcessor.EventType_.RESPONSE);
+  webdriver.LocalCommandProcessor.superClass_.dispose.call(this);
+};
+
+
+/**
+ * Event handler for command responses.
+ * @param {webdriver.Command} command The initiating command.
+ * @param {Event} e The response event. The target should be a node with a
+ *     {@code response} attribute.
+ */
+webdriver.LocalCommandProcessor.onResponse_ = function(command, e) {
+  // It is technically possible that the response could be for a different
+  // command, but this should be prevented by code higher in the WebDriverJS
+  // stack, so we don't do any error checking here.
+  if (e.type != webdriver.LocalCommandProcessor.EventType_.RESPONSE) {
+    throw Error('Not a response event!');
+  }
+
+  var jsonResponse = e.target.getAttribute(
+      webdriver.LocalCommandProcessor.MessageAttribute_.RESPONSE);
+  if (!jsonResponse) {
+    throw Error('Empty response!');
+  }
+
+  var rawResponse = goog.json.parse(jsonResponse);
+  webdriver.logging.info(
+      'receiving:\n' +
+      webdriver.logging.describe(rawResponse, '  '));
+
+  var response = new webdriver.Response(
+      rawResponse['isError'],
+      webdriver.Context.fromString(rawResponse['context']),
+      rawResponse['response']);
+  response.extraData['resultType'] = rawResponse['resultType'];
+
+  // Only code in this file should be dispatching command events and listening
+  // for response events, so this is safe. If someone else decided to attach a
+  // listener anyway, tough luck.
+  goog.events.removeAll(
+      e.target, webdriver.LocalCommandProcessor.EventType_.RESPONSE);
+  command.setResponse(response);
+};
+
+
+/**
+ * @override
+ */
+webdriver.LocalCommandProcessor.prototype.executeDriverCommand = function(
+    command, sessionId, context) {
+  if (command.name == webdriver.CommandName.SEND_KEYS) {
+    command.parameters = [command.parameters.join('')];
+  }
+
+  var jsonCommand = {
+    'commandName': command.name,
+    'context': context.toString(),
+    'parameters': command.parameters
+  };
+
+  if (command.element) {
+    jsonCommand['elementId'] = command.element.getId().getValue();
+  }
+
+  webdriver.logging.info(
+      'sending:\n' +
+      webdriver.logging.describe(jsonCommand, '  '));
+
+  this.documentElement_.setAttribute(
+      webdriver.LocalCommandProcessor.MessageAttribute_.COMMAND,
+      goog.json.serialize(jsonCommand));
+
+  goog.events.listen(this.documentElement_,
+      webdriver.LocalCommandProcessor.EventType_.RESPONSE,
+      goog.bind(webdriver.LocalCommandProcessor.onResponse_, null, command));
+
+  var commandEvent = this.dom_.getDocument().createEvent('Event');
+  commandEvent.initEvent(
+      webdriver.LocalCommandProcessor.EventType_.COMMAND,
+      /*canBubble=*/true, /*cancelable=*/true);
+  this.documentElement_.dispatchEvent(commandEvent);
+};