[js] Port the By class to node with ES2015

jleyba · jleyba · commit 5d2f38aa7e71 · 2015-11-18T10:35:04.000-08:00
Still maintains the legacy locator class (which is defined using the
closure library) as a super type to maintain compatibility with the
core WebDriver class (which is still defined using the closure library).
diff --git a/javascript/node/deploy.js b/javascript/node/deploy.js
@@ -344,6 +344,7 @@ function copyResources(outputDirPath, resources, exclusions) {
 
 function generateDocs(outputDir, callback) {
   var libDir = path.join(outputDir, 'lib');
+
   var excludedDirs = [
     path.join(outputDir, 'example'),
     path.join(libDir, 'test'),
@@ -352,6 +353,7 @@ function generateDocs(outputDir, callback) {
   ];
 
   var excludedFiles = [
+    path.join(libDir, '_base.js'),
     path.join(libDir, 'safari/client.js'),
     path.join(libDir, 'webdriver/builder.js'),
     path.join(libDir, 'webdriver/firefoxdomexecutor.js'),
@@ -383,7 +385,9 @@ function generateDocs(outputDir, callback) {
     return files;
   };
 
-  var sourceFiles = getFiles(libDir);
+  var sourceFiles = getFiles(libDir).filter(function(file) {
+    return path.dirname(file) !== libDir;
+  });
   var moduleFiles = getFiles(outputDir).filter(function(file) {
     return sourceFiles.indexOf(file) == -1;
   });
diff --git a/javascript/node/selenium-webdriver/CHANGES.md b/javascript/node/selenium-webdriver/CHANGES.md
@@ -12,6 +12,11 @@
     the W3C spec and _not_ the numeric code used by the Selenium project's
     wire protocol.
 
+### Changes for W3C WebDriver Spec Compliance
+
+* Updated the `By` locators that are not in the W3C spec to delegated to using
+    CSS selectors: `By.className`, `By.id`, `By.name`, and `By.tagName`.
+
 ## v2.48.2
 
 * Added `WebElement#takeScreenshot()`.
diff --git a/javascript/node/selenium-webdriver/index.js b/javascript/node/selenium-webdriver/index.js
@@ -38,8 +38,7 @@ exports.ActionSequence = base.require('webdriver.ActionSequence');
 exports.Builder = builder.Builder;
 
 
-/** @type {webdriver.By.} */
-exports.By = base.require('webdriver.By');
+exports.By = require('./lib/by').By;
 
 
 /** @type {function(new: webdriver.Capabilities)} */
diff --git a/javascript/node/selenium-webdriver/lib/by.js b/javascript/node/selenium-webdriver/lib/by.js
@@ -0,0 +1,280 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you 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';
+
+/**
+ * @fileoverview Factory methods for the supported locator strategies.
+ */
+
+const LegacyBy = require('./_base').require('webdriver.Locator');
+
+/**
+ * Short-hand expressions for the primary element locator strategies.
+ * For example the following two statements are equivalent:
+ *
+ *     var e1 = driver.findElement(By.id('foo'));
+ *     var e2 = driver.findElement({id: 'foo'});
+ *
+ * Care should be taken when using JavaScript minifiers (such as the
+ * Closure compiler), as locator hashes will always be parsed using
+ * the un-obfuscated properties listed.
+ *
+ * @typedef {(
+ *     {className: string}|
+ *     {css: string}|
+ *     {id: string}|
+ *     {js: string}|
+ *     {linkText: string}|
+ *     {name: string}|
+ *     {partialLinkText: string}|
+ *     {tagName: string}|
+ *     {xpath: string})}
+ */
+var ByHash;
+
+
+/**
+ * Error thrown if an invalid character is encountered while escaping a CSS
+ * identifier.
+ * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ */
+class InvalidCharacterError extends Error {
+  constructor(msg) {
+    super(msg);
+    this.name = this.constructor.name;
+  }
+}
+
+
+/**
+ * Escapes a CSS string.
+ * @param {string} css the string to escape.
+ * @return {string} the escaped string.
+ * @throws {TypeError} if the input value is not a string.
+ * @throws {InvalidCharacterError} if the string contains an invalid character.
+ * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ */
+function escapeCss(css) {
+  if (typeof css !== 'string') {
+    throw new TypeError('input must be a string');
+  }
+  let ret = '';
+  const n = css.length;
+  for (let i = 0; i  < n; i++) {
+    const c = css.charCodeAt(i);
+    if (c == 0x0) {
+      throw new InvalidCharacterError();
+    }
+
+    if ((c >= 0x0001 && c <= 0x001F)
+        || c == 0x007F
+        || (i == 0 && c >= 0x0030 && c <= 0x0039)
+        || (i == 1 && c >= 0x0030 && c <= 0x0039
+            && css.charCodeAt(0) == 0x002D)) {
+      ret += '\\' + c.toString(16);
+      continue;
+    }
+
+    if (i == 0 && c == 0x002D && n == 1) {
+      ret += '\\' + css.charAt(i);
+      continue;
+    }
+
+    if (c >= 0x0080
+        || c == 0x002D                      // -
+        || c == 0x005F                      // _
+        || (c >= 0x0030 && c <= 0x0039)     // [0-9]
+        || (c >= 0x0041 && c <= 0x005A)     // [A-Z]
+        || (c >= 0x0061 && c <= 0x007A)) {  // [a-z]
+      ret += css.charAt(i);
+      continue;
+    }
+
+    ret += '\\' + css.charAt(i);
+  }
+  return ret;
+}
+
+
+/**
+ * Describes a mechanism for locating an element on the page.
+ * @final
+ */
+class By extends LegacyBy {
+  /**
+   * @param {string} using the name of the location strategy to use.
+   * @param {string} value the value to search for.
+   */
+  constructor(using, value) {
+    // TODO: this is a legacy hack that can be removed once fully off closure.
+    super(using, value);
+
+    /** @type {string} */
+    this.using = using;
+
+    /** @type {string} */
+    this.value = value;
+  }
+
+  /**
+   * Locates elements that have a specific class name.
+   *
+   * @param {string} className The class name to search for.
+   * @return {!By} The new locator.
+   * @see http://www.w3.org/TR/2011/WD-html5-20110525/elements.html#classes
+   * @see http://www.w3.org/TR/CSS2/selector.html#class-html
+   */
+  static className(name) {
+    let names = name.split(/\s+/g)
+        .filter(s => s.length > 0)
+        .map(s => escapeCss(s));
+    return By.css('.' + names.join('.'));
+  }
+
+  /**
+   * Locates elements using a CSS selector.
+   *
+   * @param {string} selector The CSS selector to use.
+   * @return {!By} The new locator.
+   * @see http://www.w3.org/TR/CSS2/selector.html
+   */
+  static css(selector) {
+    return new By('css selector', selector);
+  }
+
+  /**
+   * Locates eleemnts by the ID attribute. This locator uses the CSS selector
+   * `*[id="$ID"]`, _not_ `document.getElementById`.
+   *
+   * @param {string} id The ID to search for.
+   * @return {!By} The new locator.
+   */
+  static id(id) {
+    return By.css('*[id="' + escapeCss(id) + '"]');
+  }
+
+  /**
+   * Locates link elements whose
+   * {@linkplain webdriver.WebElement#getText visible text} matches the given
+   * string.
+   *
+   * @param {string} text The link text to search for.
+   * @return {!By} The new locator.
+   */
+  static linkText(text) {
+    return new By('link text', text);
+  }
+
+  /**
+   * Locates an elements by evaluating a
+   * {@linkplain webdriver.WebDriver#executeScript JavaScript expression}.
+   * The result of this expression must be an element or list of elements.
+   *
+   * @param {!(string|Function)} script The script to execute.
+   * @param {...*} var_args The arguments to pass to the script.
+   * @return {function(!webdriver.WebDriver): !webdriver.promise.Promise} A new,
+   *     JavaScript-based locator function.
+   */
+  static js(script, var_args) {
+    let args = Array.slice.call(arguments, 0);
+    return function(driver) {
+      return driver.executeScript.apply(driver, args);
+    };
+  }
+
+  /**
+   * Locates elements whose `name` attribute has the given value.
+   *
+   * @param {string} name The name attribute to search for.
+   * @return {!By} The new locator.
+   */
+  static name(name) {
+    return By.css('*[name="' + escapeCss(name) + '"]');
+  }
+
+  /**
+   * Locates link elements whose 
+   * {@linkplain webdriver.WebElement#getText visible text} contains the given
+   * substring.
+   *
+   * @param {string} text The substring to check for in a link's visible text.
+   * @return {!By} The new locator.
+   */
+  static partialLinkText(text) {
+    return new By('partial link text', text);
+  }
+
+  /**
+   * Locates elements with a given tag name.
+   *
+   * @param {string} name The tag name to search for.
+   * @return {!By} The new locator.
+   * @deprecated Use {@link By.css() By.css(tagName)} instead.
+   */
+  static tagName(name) {
+    return By.css(name);
+  }
+
+  /**
+   * Locates elements matching a XPath selector. Care should be taken when
+   * using an XPath selector with a {@link webdriver.WebElement} as WebDriver
+   * will respect the context in the specified in the selector. For example,
+   * given the selector `//div`, WebDriver will search from the document root
+   * regardless of whether the locator was used with a WebElement.
+   *
+   * @param {string} xpath The XPath selector to use.
+   * @return {!By} The new locator.
+   * @see http://www.w3.org/TR/xpath/
+   */
+  static xpath(xpath) {
+    return new By('xpath', xpath);
+  }
+
+  /** @override */
+  toString() {
+    return this.constructor.name + '(' + this.using + ', ' + this.value + ')';
+  }
+}
+
+
+/**
+ * Checks if a value is a valid locator.
+ * @param {(By|Function|ByHash)} locator The value to check.
+ * @return {(By|Function)} The valid locator.
+ * @throws {TypeError} If the given value does not define a valid locator
+ *     strategy.
+ */
+function check(locator) {
+  if (locator instanceof By || typeof locator === 'function') {
+    return locator;
+  }
+  for (let key in locator) {
+    if (locator.hasOwnProperty(key) && By.hasOwnProperty(key)) {
+      return By[key](locator[key]);
+    }
+  }
+  throw new TypeError('Invalid locator');
+}
+
+
+
+// PUBLIC API
+
+
+exports.By = By;
+exports.checkedLocator = check;
diff --git a/javascript/node/selenium-webdriver/test/element_finding_test.js b/javascript/node/selenium-webdriver/test/element_finding_test.js
@@ -241,11 +241,11 @@ test.suite(function(env) {
         });
       });
 
-      test.it('does not permit compound class names', function() {
-        driver.get(Pages.xhtmlTestPage);
-        driver.findElement(By.className('a b')).then(fail, pass);
-        driver.findElements(By.className('a b')).then(fail, pass);
-        function pass() {}
+      test.it('permits compound class names', function() {
+        return driver.get(Pages.xhtmlTestPage)
+            .then(() => driver.findElement(By.className('nameA nameC')))
+            .then(el => el.getText())
+            .then(text => assert(text).equalTo('An H2 title'));
       });
     });
 
diff --git a/javascript/node/selenium-webdriver/test/lib/by_test.js b/javascript/node/selenium-webdriver/test/lib/by_test.js
