[js] Add support for W3C compliant servers

Author: jleyba

javascript/node/selenium-webdriver/CHANGES.md

@@ -10,6 +10,14 @@
    command to test for the presence of an element:
 
       driver.findElements(By.css('.foo')).then(found => !!found.length);
+* Added support for W3C-spec compliant servers.
+
+### Changes for W3C WebDriver Spec Compliance
+
+* Changed `element.sendKeys(...)` to send the key sequence as an array where
+   each element defines a single key. The legacy wire protocol permits arrays
+   where each element is a string of arbitrary length. This change is solely
+   at the protocol level and should have no user-visible effect.
 
 
 ## v2.52.0

javascript/node/selenium-webdriver/error.js

@@ -546,6 +546,7 @@ const ERROR_CODE_TO_TYPE = new Map([
  * @param {*} data The response data to check.
  * @return {*} The response data if it was not an encoded error.
  * @throws {WebDriverError} the decoded error, if present in the data object.
+ * @deprecated Use {@link #throwDecodedError(data)} instead.
  * @see https://w3c.github.io/webdriver/webdriver-spec.html#protocol
  */
 function checkResponse(data) {
@@ -557,6 +558,23 @@ function checkResponse(data) {
 }
 
 
+/**
+ * Throws an error coded from the W3C protocol. A generic error will be thrown
+ * if the privded `data` is not a valid encoded error.
+ *
+ * @param {{error: string, message: string}} data The error data to decode.
+ * @throws {WebDriverError} the decoded error.
+ * @see https://w3c.github.io/webdriver/webdriver-spec.html#protocol
+ */
+function throwDecodedError(data) {
+  if (data && typeof data === 'object' && typeof data.error === 'string') {
+    let ctor = ERROR_CODE_TO_TYPE.get(data.error) || WebDriverError;
+    throw new ctor(data.message);
+  }
+  throw new WebDriverError('Unknown error: ' + JSON.stringify(data));
+}
+
+
 /**
  * Checks a legacy response from the Selenium 2.0 wire protocol for an error.
  * @param {*} responseObj the response object to check.
@@ -626,3 +644,4 @@ exports.UnsupportedOperationError = UnsupportedOperationError;
 
 exports.checkResponse = checkResponse;
 exports.checkLegacyResponse = checkLegacyResponse;
+exports.throwDecodedError = throwDecodedError;

javascript/node/selenium-webdriver/http/index.js

@@ -156,11 +156,11 @@ const COMMAND_MAP = new Map([
     [cmd.Name.ELEMENT_EQUALS, get('/session/:sessionId/element/:id/equals/:other')],
     [cmd.Name.TAKE_ELEMENT_SCREENSHOT, get('/session/:sessionId/element/:id/screenshot')],
     [cmd.Name.SWITCH_TO_WINDOW, post('/session/:sessionId/window')],
-    [cmd.Name.MAXIMIZE_WINDOW, post('/session/:sessionId/window/:windowHandle/maximize')],
-    [cmd.Name.GET_WINDOW_POSITION, get('/session/:sessionId/window/:windowHandle/position')],
-    [cmd.Name.SET_WINDOW_POSITION, post('/session/:sessionId/window/:windowHandle/position')],
-    [cmd.Name.GET_WINDOW_SIZE, get('/session/:sessionId/window/:windowHandle/size')],
-    [cmd.Name.SET_WINDOW_SIZE, post('/session/:sessionId/window/:windowHandle/size')],
+    [cmd.Name.MAXIMIZE_WINDOW, post('/session/:sessionId/window/current/maximize')],
+    [cmd.Name.GET_WINDOW_POSITION, get('/session/:sessionId/window/current/position')],
+    [cmd.Name.SET_WINDOW_POSITION, post('/session/:sessionId/window/current/position')],
+    [cmd.Name.GET_WINDOW_SIZE, get('/session/:sessionId/window/current/size')],
+    [cmd.Name.SET_WINDOW_SIZE, post('/session/:sessionId/window/current/size')],
     [cmd.Name.SWITCH_TO_FRAME, post('/session/:sessionId/frame')],
     [cmd.Name.GET_PAGE_SOURCE, get('/session/:sessionId/source')],
     [cmd.Name.GET_TITLE, get('/session/:sessionId/title')],
@@ -196,6 +196,14 @@ const COMMAND_MAP = new Map([
 ]);
 
 
+/** @const {!Map<string, {method: string, path: string}>} */
+const W3C_COMMAND_MAP = new Map([
+  [cmd.Name.GET_WINDOW_SIZE, get('/session/:sessionId/window/size')],
+  [cmd.Name.SET_WINDOW_SIZE, post('/session/:sessionId/window/size')],
+  [cmd.Name.MAXIMIZE_WINDOW, post('/session/:sessionId/window/maximize')],
+]);
+
+
 /**
  * A basic HTTP client used to send messages to a remote end.
  */
@@ -377,6 +385,15 @@ function sendRequest(options, onOk, onError, opt_data, opt_proxy) {
 
 /**
  * A command executor that communicates with the server using HTTP + JSON.
+ *
+ * By default, each instance of this class will use the legacy wire protocol
+ * from [Selenium project][json]. The executor will automatically switch to the
+ * [W3C wire protocol][w3c] if the remote end returns a compliant response to
+ * a new session command.
+ *
+ * [json]: https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol
+ * [w3c]: https://w3c.github.io/webdriver/webdriver-spec.html
+ *
  * @implements {cmd.Executor}
  */
 class Executor {
@@ -388,6 +405,15 @@ class Executor {
     /** @private {!HttpClient} */
     this.client_ = client;
 
+    /**
+     * Whether this executor should use the W3C wire protocol. The executor
+     * will automatically switch if the remote end sends a compliant response
+     * to a new session command, however, this property may be directly set to
+     * `true` to force the executor into W3C mode.
+     * @type {boolean}
+     */
+    this.w3c = false;
+
     /** @private {Map<string, {method: string, path: string}>} */
     this.customCommands_ = null;
 
@@ -419,6 +445,7 @@ class Executor {
   execute(command) {
     let resource =
         (this.customCommands_ && this.customCommands_.get(command.getName()))
+        || (this.w3c && W3C_COMMAND_MAP.get(command.getName()))
         || COMMAND_MAP.get(command.getName());
     if (!resource) {
       throw new error.UnknownCommandError(
@@ -431,19 +458,26 @@ class Executor {
 
     let log = this.log_;
     log.finer(() => '>>>\n' + request);
-    return this.client_.send(request).then(function(response) {
+    return this.client_.send(request).then(response => {
       log.finer(() => '<<<\n' + response);
 
-      let value = parseHttpResponse(/** @type {!HttpResponse} */ (response));
-      let isResponseObj = (value && typeof value === 'object');
+      let parsed =
+          parseHttpResponse(/** @type {!HttpResponse} */ (response), this.w3c);
+
       if (command.getName() === cmd.Name.NEW_SESSION) {
-        if (!isResponseObj) {
+        if (!parsed || !parsed['sessionId']) {
           throw new error.WebDriverError(
               'Unable to parse new session response: ' + response.body);
         }
-        return new Session(value['sessionId'], value['value']);
+
+        // The remote end is a W3C compliant server if there is no `status`
+        // field in the response.
+        this.w3c = this.w3c || !('status' in parsed);
+
+        return new Session(parsed['sessionId'], parsed['value']);
       }
-      return isResponseObj ? value['value'] : value;
+
+      return parsed ? (parsed['value'] || null) : parsed;
     });
   }
 }
@@ -466,29 +500,46 @@ function tryParse(str) {
  * Callback used to parse {@link HttpResponse} objects from a
  * {@link HttpClient}.
  * @param {!HttpResponse} httpResponse The HTTP response to parse.
- * @return {!Object} The parsed response.
+ * @param {boolean} w3c Whether the response should be processed using the
+ *     W3C wire protocol.
+ * @return {{value: ?}} The parsed response.
+ * @throws {WebDriverError} If the HTTP response is an error.
  */
-function parseHttpResponse(httpResponse) {
+function parseHttpResponse(httpResponse, w3c) {
   let parsed = tryParse(httpResponse.body);
   if (parsed !== undefined) {
-    error.checkLegacyResponse(parsed);
-    return parsed;
+    if (w3c) {
+      if (httpResponse.status > 399) {
+        error.throwDecodedError(parsed);
+      }
+
+      if (httpResponse.status < 200) {
+        // This should never happen, but throw the raw response so
+        // users report it.
+        throw error.WebDriverError(
+            `Unexpected HTTP response:\n${httpResponse}`);
+      }
+    } else {
+      error.checkLegacyResponse(parsed);
+    }
+
+    if (!parsed || typeof parsed !== 'object') {
+      parsed = {value: parsed};
+    }
+    return parsed
   }
 
   let value = httpResponse.body.replace(/\r\n/g, '\n');
-  if (!value) {
-    return null;
-  }
 
-  // 404 represents an unknown command; anything else is a generic unknown
+  // 404 represents an unknown command; anything else > 399 is a generic unknown
   // error.
   if (httpResponse.status == 404) {
     throw new error.UnsupportedOperationError(value);
   } else if (httpResponse.status >= 400) {
     throw new error.WebDriverError(value);
   }
 
-  return value;
+  return value ? {value: value} : null;
 }
 
 

javascript/node/selenium-webdriver/lib/webdriver.js

@@ -1861,7 +1861,19 @@ class WebElement {
     // ignore the jsdoc and give us a number (which ends up causing problems on
     // the server, which requires strings).
     let keys = promise.all(Array.prototype.slice.call(arguments, 0)).
-        then(keys => keys.map(String));
+        then(keys => {
+          let ret = [];
+          keys.forEach(key => {
+            if (typeof key !== 'string') {
+              key = String(key);
+            }
+
+            // The W3C protocol requires keys to be specified as an array where
+            // each element is a single key.
+            ret.push.apply(ret, key.split(''));
+          });
+          return ret;
+        });
     if (!this.driver_.fileDetector_) {
       return this.schedule_(
           new command.Command(command.Name.SEND_KEYS_TO_ELEMENT).

javascript/node/selenium-webdriver/test/error_test.js

@@ -77,6 +77,79 @@ describe('error', function() {
     }
   });
 
+  describe('throwDecodedError', function() {
+    it('defaults to WebDriverError if type is unrecognized', function() {
+      assert.throws(
+          () => error.throwDecodedError({error: 'foo', message: 'hi there'}),
+          (e) => {
+            assert.equal(e.constructor, error.WebDriverError);
+            assert.equal(e.code, error.ErrorCode.UNKNOWN_ERROR);
+            return true;
+          });
+    });
+
+    it('throws generic error if encoded data is not valid', function() {
+      assert.throws(
+          () => error.throwDecodedError({error: 123, message: 'abc123'}),
+          (e) => {
+            assert.strictEqual(e.constructor, error.WebDriverError);
+            return true;
+          });
+
+      assert.throws(
+          () => error.throwDecodedError('null'),
+          (e) => {
+            assert.strictEqual(e.constructor, error.WebDriverError);
+            return true;
+          });
+
+      assert.throws(
+          () => error.throwDecodedError(''),
+          (e) => {
+            assert.strictEqual(e.constructor, error.WebDriverError);
+            return true;
+          });
+    });
+
+    test('unknown error', error.WebDriverError);
+    test('element not selectable', error.ElementNotSelectableError);
+    test('element not visible', error.ElementNotVisibleError);
+    test('invalid argument', error.InvalidArgumentError);
+    test('invalid cookie domain', error.InvalidCookieDomainError);
+    test('invalid element coordinates', error.InvalidElementCoordinatesError);
+    test('invalid element state', error.InvalidElementStateError);
+    test('invalid selector', error.InvalidSelectorError);
+    test('invalid session id', error.InvalidSessionIdError);
+    test('javascript error', error.JavascriptError);
+    test('move target out of bounds', error.MoveTargetOutOfBoundsError);
+    test('no such alert', error.NoSuchAlertError);
+    test('no such element', error.NoSuchElementError);
+    test('no such frame', error.NoSuchFrameError);
+    test('no such window', error.NoSuchWindowError);
+    test('script timeout', error.ScriptTimeoutError);
+    test('session not created', error.SessionNotCreatedError);
+    test('stale element reference', error.StaleElementReferenceError);
+    test('timeout', error.TimeoutError);
+    test('unable to set cookie', error.UnableToSetCookieError);
+    test('unable to capture screen', error.UnableToCaptureScreenError);
+    test('unexpected alert open', error.UnexpectedAlertOpenError);
+    test('unknown command', error.UnknownCommandError);
+    test('unknown method', error.UnknownMethodError);
+    test('unsupported operation', error.UnsupportedOperationError);
+
+    function test(status, expectedType) {
+      it(`"${status}" => ${expectedType.name}`, function() {
+        assert.throws(
+            () => error.throwDecodedError({error: status, message: 'oops'}),
+            (e) => {
+              assert.strictEqual(e.constructor, expectedType);
+              assert.strictEqual(e.message, 'oops');
+              return true;
+            });
+      });
+    }
+  });
+
   describe('checkLegacyResponse', function() {
     it('does not throw for success', function() {
       let resp = {status: error.ErrorCode.SUCCESS};