Add support for custom command mappings in the node bindings.

Fixes issue 8221

Author: jleyba

javascript/node/selenium-webdriver/CHANGES.md

@@ -3,6 +3,9 @@
 * Promise rejections are now always coerced to Error-like objects (an object
     with a string `message` property). We do not guarantee `instanceof Error`
     since the rejection value may come from another context.
+* FIXED: 8221: Added support for defining custom command mappings. Includes
+    support for PhantomJS's `executePhantomJS` (requires PhantomJS 1.9.7 or
+    GhostDriver 1.1.0).
 * FIXED: 8128: When the FirefoxDriver marshals an object to the page for
     `executeScript`, it defines additional properties (required by the driver's
     implementation). These properties will no longer be enumerable and should

javascript/node/selenium-webdriver/executors.js

@@ -45,6 +45,8 @@ var DeferredExecutor = function(delegate) {
 // PUBLIC API
 
 
+exports.DeferredExecutor = DeferredExecutor;
+
 /**
  * Creates a command executor that uses WebDriver's JSON wire protocol.
  * @param {(string|!webdriver.promise.Promise.<string>)} url The server's URL,

javascript/node/selenium-webdriver/phantomjs.js

@@ -20,6 +20,7 @@ var fs = require('fs'),
 
 var webdriver = require('./index'),
     executors = require('./executors'),
+    http = require('./http'),
     io = require('./io'),
     portprober = require('./net/portprober'),
     remote = require('./remote');
@@ -58,6 +59,15 @@ var CLI_ARGS_CAPABILITY = 'phantomjs.cli.args';
 var DEFAULT_LOG_FILE = 'phantomjsdriver.log';
 
 
+/**
+ * Custom command names supported by PhantomJS.
+ * @enum {string}
+ */
+var Command = {
+  EXECUTE_PHANTOM_SCRIPT: 'executePhantomScript'
+};
+
+
 /**
  * Finds the PhantomJS executable.
  * @param {string=} opt_exe Path to the executable to use.
@@ -111,6 +121,24 @@ function createDriver(opt_capabilities, opt_flow) {
 }
 
 
+/**
+ * Creates a command executor with support for PhantomJS' custom commands.
+ * @param {!webdriver.promise.Promise<string>} url The server's URL.
+ * @return {!webdriver.CommandExecutor} The new command executor.
+ */
+function createExecutor(url) {
+  return new executors.DeferredExecutor(url.then(function(url) {
+    var client = new http.HttpClient(url);
+    var executor = new http.Executor(client);
+
+    executor.defineCommand(
+        Command.EXECUTE_PHANTOM_SCRIPT,
+        'POST', '/session/:sessionId/phantom/execute');
+
+    return executor;
+  }));
+}
+
 /**
  * Creates a new WebDriver client for PhantomJS.
  *
@@ -169,7 +197,7 @@ var Driver = function(opt_capabilities, opt_flow) {
     })
   });
 
-  var executor = executors.createExecutor(service.start());
+  var executor = createExecutor(service.start());
   var driver = webdriver.WebDriver.createSession(
       executor, capabilities, opt_flow);
 
@@ -186,6 +214,54 @@ var Driver = function(opt_capabilities, opt_flow) {
 util.inherits(Driver, webdriver.WebDriver);
 
 
+/**
+ * Executes a PhantomJS fragment. This method is similar to
+ * {@link #executeScript}, except it exposes the
+ * <a href="http://phantomjs.org/api/">PhantomJS API</a> to the injected
+ * script.
+ *
+ * <p>The injected script will execute in the context of PhantomJS's
+ * {@code page} variable. If a page has not been loaded before calling this
+ * method, one will be created.</p>
+ *
+ * <p>Be sure to wrap callback definitions in a try/catch block, as failures
+ * may cause future WebDriver calls to fail.</p>
+ *
+ * <p>Certain callbacks are used by GhostDriver (the PhantomJS WebDriver
+ * implementation) and overriding these may cause the script to fail. It is
+ * recommended that you check for existing callbacks before defining your own.
+ * </p>
+ *
+ * As with {@link #executeScript}, the injected script may be defined as
+ * a string for an anonymous function body (e.g. "return 123;"), or as a
+ * function. If a function is provided, it will be decompiled to its original
+ * source. Note that injecting functions is provided as a convenience to
+ * simplify defining complex scripts. Care must be taken that the function
+ * only references variables that will be defined in the page's scope and
+ * that the function does not override {@code Function.prototype.toString}
+ * (overriding toString() will interfere with how the function is
+ * decompiled.
+ *
+ * @param {(string|!Function)} script The script to execute.
+ * @param {...*} var_args The arguments to pass to the script.
+ * @return {!webdriver.promise.Promise<T>} A promise that resolve to the
+ *     script's return value.
+ * @template T
+ */
+Driver.prototype.executePhantomJS = function(script, args) {
+  if (typeof script === 'function') {
+    script = 'return (' + script + ').apply(this, arguments);';
+  }
+  var args = arguments.length > 1
+      ? Array.prototype.slice.call(arguments, 1) : [];
+  return this.schedule(
+      new webdriver.Command(Command.EXECUTE_PHANTOM_SCRIPT)
+          .setParameter('script', script)
+          .setParameter('args', args),
+      'Driver.executePhantomJS()');
+};
+
+
 // PUBLIC API
 
 exports.Driver = Driver;

javascript/node/selenium-webdriver/test/phantomjs/execute_phantomjs_test.js

@@ -0,0 +1,71 @@
+// Copyright 2015 Selenium committers
+// Copyright 2015 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.
+
+'use strict';
+
+var assert = require('assert');
+var path = require('path');
+var test = require('../../lib/test');
+
+test.suite(function(env) {
+  var driver;
+
+  test.before(function() {
+    driver = env.builder().build();
+  });
+
+  test.after(function() {
+    driver.quit();
+  });
+
+  var testPageUrl =
+      'data:text/html,<html><h1>' + path.basename(__filename) + '</h1></html>';
+
+  test.beforeEach(function() {
+    driver.get(testPageUrl);
+  });
+
+  describe('phantomjs.Driver', function() {
+    describe('#executePhantomJS()', function() {
+
+      test.it('can execute scripts using PhantomJS API', function() {
+        return driver.executePhantomJS('return this.url;').then(function(url) {
+          assert.equal(testPageUrl, url);
+        });
+      });
+
+      test.it('can execute scripts as functions', function() {
+        driver.executePhantomJS(function(a, b) {
+          return a + b;
+        }, 1, 2).then(function(result) {
+          assert.equal(3, result);
+        });
+      });
+
+      test.it('can manipulate the current page', function() {
+        driver.manage().addCookie('foo', 'bar');
+        driver.manage().getCookie('foo').then(function(cookie) {
+          assert.equal('bar', cookie.value);
+        });
+        driver.executePhantomJS(function() {
+          this.clearCookies();
+        });
+        driver.manage().getCookie('foo').then(function(cookie) {
+          assert.equal(null, cookie);
+        });
+      });
+    });
+  });
+}, {browsers: ['phantomjs']});

javascript/webdriver/http/http.js

@@ -70,12 +70,38 @@ webdriver.http.Executor = function(client) {
    * @private {!webdriver.http.Client}
    */
   this.client_ = client;
+
+  /**
+   * @private {!Object<{method:string, path:string}>}
+   */
+  this.customCommands_ = {};
+};
+
+
+/**
+ * Defines a new command for use with this executor. When a command is sent,
+ * the {@code path} will be preprocessed using the command's parameters; any
+ * path segments prefixed with ":" will be replaced by the parameter of the
+ * same name. For example, given "/person/:name" and the parameters
+ * "{name: 'Bob'}", the final command path will be "/person/Bob".
+ *
+ * @param {string} name The command name.
+ * @param {string} method The HTTP method to use when sending this command.
+ * @param {string} pathPattern The path to send the command to, relative to
+ *     the WebDriver server's command root and of the form
+ *     "/path/:variable/segment".
+ */
+webdriver.http.Executor.prototype.defineCommand = function(
+    name, method, path) {
+  this.customCommands_[name] = {method: method, path: path};
 };
 
 
 /** @override */
 webdriver.http.Executor.prototype.execute = function(command, callback) {
-  var resource = webdriver.http.Executor.COMMAND_MAP_[command.getName()];
+  var resource =
+      this.customCommands_[command.getName()] ||
+      webdriver.http.Executor.COMMAND_MAP_[command.getName()];
   if (!resource) {
     throw new Error('Unrecognized command: ' + command.getName());
   }

javascript/webdriver/test/http/http_test.js

@@ -328,6 +328,36 @@ function testExecute_attemptsToParseBodyWhenNoContentTypeSpecified() {
   });
 }
 
+function testCanDefineNewCommands() {
+  executor.defineCommand('greet', 'GET', '/person/:name');
+
+  var command = new webdriver.Command('greet').
+      setParameter('name', 'Bob');
+
+  expectRequest('GET', '/person/Bob', {},
+      {'Accept': 'application/json; charset=utf-8'}).
+      $does(respondsWith(null, response(200, {}, '')));
+  control.$replayAll();
+
+  assertSendsSuccessfully(command);
+}
+
+function testCanRedefineStandardCommands() {
+  executor.defineCommand(webdriver.CommandName.GO_BACK,
+      'POST', '/custom/back');
+
+  var command = new webdriver.Command(webdriver.CommandName.GO_BACK).
+      setParameter('times', 3);
+
+  expectRequest('POST', '/custom/back',
+      {'times': 3},
+      {'Accept': 'application/json; charset=utf-8'}).
+      $does(respondsWith(null, response(200, {}, '')));
+  control.$replayAll();
+
+  assertSendsSuccessfully(command);
+}
+
 function FakeXmlHttpRequest(headers, status, responseText) {
   return {
     getAllResponseHeaders: function() { return headers; },