Introduce a new serializable type.

This is used for types that cannot be synchronously converted to their
JSON wire format (synchronous types may continue using the standard
toJSON() function)

Author: jleyba

javascript/node/selenium-webdriver/chrome.js

@@ -229,14 +229,18 @@ var OPTIONS_CAPABILITY_KEY = 'chromeOptions';
 /**
  * Class for managing ChromeDriver specific options.
  * @constructor
+ * @extends {webdriver.Serializable}
  */
 var Options = function() {
+  webdriver.Serializable.call(this);
+
   /** @private {!Array.<string>} */
   this.args_ = [];
 
   /** @private {!Array.<(string|!Buffer)>} */
   this.extensions_ = [];
 };
+util.inherits(Options, webdriver.Serializable);
 
 
 /**
@@ -415,21 +419,23 @@ Options.prototype.toCapabilities = function(opt_capabilities) {
  * @return {{args: !Array.<string>,
  *           binary: (string|undefined),
  *           detach: boolean,
- *           extensions: !Array.<string>,
+ *           extensions: !Array.<(string|!webdriver.promise.Promise.<string>))>,
  *           localState: (Object|undefined),
  *           logPath: (string|undefined),
  *           prefs: (Object|undefined)}} The JSON wire protocol representation
  *     of this instance.
+ * @override
  */
-Options.prototype.toJSON = function() {
+Options.prototype.serialize = function() {
   var json = {
     args: this.args_,
     detach: !!this.detach_,
     extensions: this.extensions_.map(function(extension) {
       if (Buffer.isBuffer(extension)) {
         return extension.toString('base64');
       }
-      return fs.readFileSync(extension, 'base64');
+      return webdriver.promise.checkedNodeCall(
+          fs.readFile, extension, 'base64');
     })
   };
 

javascript/node/selenium-webdriver/firefox/binary.js

@@ -20,7 +20,8 @@ var child = require('child_process'),
     path = require('path'),
     util = require('util');
 
-var promise = require('..').promise,
+var Serializable = require('..').Serializable,
+    promise = require('..').promise,
     _base = require('../_base'),
     io = require('../io'),
     exec = require('../io/exec');
@@ -148,11 +149,15 @@ function installProfile(firefox, env) {
 
 /**
  * Manages a Firefox subprocess configured for use with WebDriver.
+ *
  * @param {string=} opt_exe Path to the Firefox binary to use. If not
  *     specified, will attempt to locate Firefox on the current system.
  * @constructor
+ * @extends {Serializable.<string>}
  */
 var Binary = function(opt_exe) {
+  Serializable.call(this);
+
   /** @private {(string|undefined)} */
   this.exe_ = opt_exe;
 
@@ -171,6 +176,7 @@ var Binary = function(opt_exe) {
   /** @private {promise.Promise.<!exec.Command>} */
   this.command_ = null;
 };
+util.inherits(Binary, Serializable);
 
 
 /**
@@ -254,6 +260,21 @@ Binary.prototype.kill = function() {
 };
 
 
+/**
+ * Returns a promise for the wire representation of this binary. Note: the
+ * FirefoxDriver only supports passing the path to the binary executable over
+ * the wire; all command line arguments and environment variables will be
+ * discarded.
+ *
+ * @return {!promise.Promise.<string>} A promise for this binary's wire
+ *     representation.
+ * @override
+ */
+Binary.prototype.serialize = function() {
+  return promise.when(this.exe_ || findFirefox());
+};
+
+
 // PUBLIC API
 
 

javascript/node/selenium-webdriver/firefox/profile.js

@@ -18,9 +18,11 @@
 var AdmZip = require('adm-zip'),
     fs = require('fs'),
     path = require('path'),
+    util = require('util'),
     vm = require('vm');
 
-var promise = require('..').promise,
+var Serializable = require('..').Serializable,
+    promise = require('..').promise,
     _base = require('../_base'),
     io = require('../io'),
     extension = require('./extension');
@@ -213,8 +215,11 @@ function decode(data) {
  *     use a template for this profile. If not specified, a blank profile will
  *     be used.
  * @constructor
+ * @extends {Serializable.<string>}
  */
 var Profile = function(opt_dir) {
+  Serializable.call(this);
+
   /** @private {!Object} */
   this.preferences_ = {};
 
@@ -233,6 +238,7 @@ var Profile = function(opt_dir) {
   /** @private {!Array.<string>} */
   this.extensions_ = [];
 };
+util.inherits(Profile, Serializable);
 
 
 /**
@@ -400,6 +406,16 @@ Profile.prototype.encode = function() {
 };
 
 
+/**
+ * Encodes this profile as a zipped, base64 encoded directory.
+ * @return {!promise.Promise.<string>} A promise for the encoded profile.
+ * @override
+ */
+Profile.prototype.serialize = function() {
+  return this.encode();
+};
+
+
 // PUBLIC API
 
 

javascript/node/selenium-webdriver/index.js

@@ -52,6 +52,10 @@ exports.Command = base.require('webdriver.Command');
 exports.EventEmitter = base.require('webdriver.EventEmitter');
 
 
+/** @type {function(new: webdriver.Serializable)} */
+exports.Serializable = base.require('webdriver.Serializable');
+
+
 /** @type {function(new: webdriver.Session)} */
 exports.Session = base.require('webdriver.Session');
 

javascript/node/selenium-webdriver/test/chrome/options_test.js

@@ -76,7 +76,7 @@ describe('chrome.Options', function() {
           });
 
           var options = chrome.Options.fromCapabilities(caps);
-          var json = options.toJSON();
+          var json = options.serialize();
 
           assert(json.args.length).equalTo(0);
           assert(json.binary).isUndefined();
@@ -152,10 +152,10 @@ describe('chrome.Options', function() {
     });
   });
 
-  describe('toJSON', function() {
+  describe('serialize', function() {
     it('base64 encodes extensions', function() {
       var expected = fs.readFileSync(__filename, 'base64');
-      var wire = new chrome.Options().addExtensions(__filename).toJSON();
+      var wire = new chrome.Options().addExtensions(__filename).serialize();
       assert(wire.extensions.length).equalTo(1);
       assert(wire.extensions[0]).equalTo(expected);
     });
@@ -194,12 +194,14 @@ describe('chrome.Options', function() {
 test.suite(function(env) {
   env.autoCreateDriver = false;
 
-  describe('options', function() {
+  describe('Chrome options', function() {
     test.it('can start Chrome with custom args', function() {
       var options = new chrome.Options().
           addArguments('user-agent=foo;bar');
 
-      var driver = env.driver = new chrome.Driver(options);
+      var driver = env.builder().
+          setChromeOptions(options).
+          build();
 
       driver.get(test.Pages.ajaxyPage);
 

javascript/node/selenium-webdriver/test/firefox/firefox_test.js

@@ -43,7 +43,10 @@ test.suite(function(env) {
 
         var options = new firefox.Options().setProfile(profile);
 
-        var driver = env.driver = new firefox.Driver(options);
+        var driver = env.builder().
+            setFirefoxOptions(options).
+            build();
+
         driver.get('data:text/html,<html><div>content</div></html>');
 
         var userAgent = driver.executeScript(
@@ -57,7 +60,10 @@ test.suite(function(env) {
 
         var options = new firefox.Options().setProfile(profile);
 
-        var driver = env.driver = new firefox.Driver(options);
+        var driver = env.builder().
+            setFirefoxOptions(options).
+            build();
+
         loadJetpackPage(driver,
             'data:text/html;charset=UTF-8,<html><div>content</div></html>');
         assert(driver.findElement({id: 'jetpack-sample-banner'}).getText())
@@ -70,7 +76,10 @@ test.suite(function(env) {
 
         var options = new firefox.Options().setProfile(profile);
 
-        var driver = env.driver = new firefox.Driver(options);
+        var driver = env.builder().
+            setFirefoxOptions(options).
+            build();
+
         driver.get('data:text/html,<html><div>content</div></html>');
         assert(driver.findElement({id: 'sample-extension-footer'}).getText())
             .equalTo('Goodbye');
@@ -83,7 +92,9 @@ test.suite(function(env) {
 
         var options = new firefox.Options().setProfile(profile);
 
-        var driver = env.driver = new firefox.Driver(options);
+        var driver = env.builder().
+            setFirefoxOptions(options).
+            build();
 
         loadJetpackPage(driver,
             'data:text/html;charset=UTF-8,<html><div>content</div></html>');

javascript/webdriver/capabilities.js

@@ -21,6 +21,7 @@ goog.provide('webdriver.Capabilities');
 goog.provide('webdriver.Capability');
 goog.provide('webdriver.ProxyConfig');
 
+goog.require('webdriver.Serializable');
 goog.require('webdriver.logging.Preferences');
 
 
@@ -161,16 +162,19 @@ webdriver.Capability = {
  * @param {(webdriver.Capabilities|Object)=} opt_other Another set of
  *     capabilities to merge into this instance.
  * @constructor
+ * @extends {webdriver.Serializable.<!Object.<string, ?>>}
  */
 webdriver.Capabilities = function(opt_other) {
+  webdriver.Serializable.call(this);
 
-  /** @private {!Object} */
+  /** @private {!Object.<string, ?>} */
   this.caps_ = {};
 
   if (opt_other) {
     this.merge(opt_other);
   }
 };
+goog.inherits(webdriver.Capabilities, webdriver.Serializable);
 
 
 /**
@@ -281,12 +285,26 @@ webdriver.Capabilities.htmlunitwithjs = function() {
 };
 
 
-/** @return {!Object} The JSON representation of this instance. */
+/**
+ * @return {!Object} The JSON representation of this instance.
+ * @deprecated Use {@link #serialize} since a component capability may be a
+ *     promised value.
+ */
 webdriver.Capabilities.prototype.toJSON = function() {
   return this.caps_;
 };
 
 
+/**
+ * @return {!Object.<string, ?>} The JSON representation of this instance. Note,
+ *    the returned object may contain nested promises that are promised values.
+ * @override
+ */
+webdriver.Capabilities.prototype.serialize = function() {
+  return this.caps_;
+};
+
+
 /**
  * Merges another set of capabilities into this instance. Any duplicates in
  * the provided set will override those already set on this instance.

javascript/webdriver/serializable.js

@@ -0,0 +1,39 @@
+// Copyright 2014 Selenium comitters
+// Copyright 2014 Software Freedom Conservancy
+//
+// 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.Serializable');
+
+
+
+/**
+ * Defines an object that can be asynchronously serialized to its WebDriver
+ * wire representation.
+ *
+ * @constructor
+ * @template T
+ */
+webdriver.Serializable = function() {};
+
+
+/**
+ * Returns either this instance's serialized represention, if immediately
+ * available, or a promise for its serialized representation. This function is
+ * conceptually equivalent to objects that have a {@code toJSON()} property,
+ * except the serialize() result may be a promise or an object containing a
+ * promise (which are not directly JSON friendly).
+ *
+ * @return {!(T|IThenable.<!T>)} This instance's serialized wire format.
+ */
+webdriver.Serializable.prototype.serialize = goog.abstractMethod;