by.js

// 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.
 */

/**
 * 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})} 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() {
    super()
    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 {
  /**
   * @param {string} using the name of the location strategy to use.
   * @param {string} value the value to search for.
   */
  constructor(using, value) {
    /** @type {string} */
    this.using = using

    /** @type {string} */
    this.value = value
  }

  /**
   * Locates elements that have a specific class name.
   *
   * @param {string} name 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 elements 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 elements by evaluating a `script` that defines the body of
   * a {@linkplain webdriver.WebDriver#executeScript JavaScript function}.
   * The return value of this function must be an element or an array-like
   * list of elements. When this locator returns a list of elements, but only
   * one is expected, the first element in this list will be used as the
   * single element value.
   *
   * @param {!(string|Function)} script The script to execute.
   * @param {...*} var_args The arguments to pass to the script.
   * @return {function(!./webdriver.WebDriver): !Promise}
   *     A new JavaScript-based locator function.
   */
  static js(script, ...var_args) {
    return function (driver) {
      return driver.executeScript.call(driver, script, ...var_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.
   */
  static tagName(name) {
    return new By('tag name', 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() {
    // The static By.name() overrides this.constructor.name.  Shame...
    return `By(${this.using}, ${this.value})`
  }

  toObject() {
    const tmp = {}
    tmp[this.using] = this.value
    return tmp
  }
}

/**
 * Start Searching for relative objects using the value returned from
 * `By.tagName()`.
 *
 * Note: this method will likely be removed in the future please use
 * `locateWith`.
 * @param {By} tagName The value returned from calling By.tagName()
 * @returns
 */
function withTagName(tagName) {
  return new RelativeBy({ 'css selector': tagName })
}

/**
 * Start searching for relative objects using search criteria with By.
 * @param {string} by A By map that shows how to find the initial element
 * @returns {RelativeBy}
 */
function locateWith(by) {
  return new RelativeBy(getLocator(by))
}

function getLocator(locatorOrElement) {
  let toFind
  if (locatorOrElement instanceof By) {
    toFind = locatorOrElement.toObject()
  } else {
    toFind = locatorOrElement
  }
  return toFind
}

/**
 * Describes a mechanism for locating an element relative to others
 * on the page.
 * @final
 */
class RelativeBy {
  /**
   * @param {By} findDetails
   * @param {Array<Object>} filters
   */
  constructor(findDetails, filters = null) {
    this.root = findDetails
    this.filters = filters || []
  }

  /**
   * Look for elements above the root element passed in
   * @param {string|WebElement} locatorOrElement
   * @return {!RelativeBy} Return this object
   */
  above(locatorOrElement) {
    this.filters.push({
      kind: 'above',
      args: [getLocator(locatorOrElement)],
    })
    return this
  }

  /**
   * Look for elements below the root element passed in
   * @param {string|WebElement} locatorOrElement
   * @return {!RelativeBy} Return this object
   */
  below(locatorOrElement) {
    this.filters.push({
      kind: 'below',
      args: [getLocator(locatorOrElement)],
    })
    return this
  }

  /**
   * Look for elements left the root element passed in
   * @param {string|WebElement} locatorOrElement
   * @return {!RelativeBy} Return this object
   */
  toLeftOf(locatorOrElement) {
    this.filters.push({
      kind: 'left',
      args: [getLocator(locatorOrElement)],
    })
    return this
  }

  /**
   * Look for elements right the root element passed in
   * @param {string|WebElement} locatorOrElement
   * @return {!RelativeBy} Return this object
   */
  toRightOf(locatorOrElement) {
    this.filters.push({
      kind: 'right',
      args: [getLocator(locatorOrElement)],
    })
    return this
  }

  /**
   * Look for elements above the root element passed in
   * @param {string|WebElement} locatorOrElement
   * @return {!RelativeBy} Return this object
   */
  straightAbove(locatorOrElement) {
    this.filters.push({
      kind: 'straightAbove',
      args: [getLocator(locatorOrElement)],
    })
    return this
  }

  /**
   * Look for elements below the root element passed in
   * @param {string|WebElement} locatorOrElement
   * @return {!RelativeBy} Return this object
   */
  straightBelow(locatorOrElement) {
    this.filters.push({
      kind: 'straightBelow',
      args: [getLocator(locatorOrElement)],
    })
    return this
  }

  /**
   * Look for elements left the root element passed in
   * @param {string|WebElement} locatorOrElement
   * @return {!RelativeBy} Return this object
   */
  straightToLeftOf(locatorOrElement) {
    this.filters.push({
      kind: 'straightLeft',
      args: [getLocator(locatorOrElement)],
    })
    return this
  }

  /**
   * Look for elements right the root element passed in
   * @param {string|WebElement} locatorOrElement
   * @return {!RelativeBy} Return this object
   */
  straightToRightOf(locatorOrElement) {
    this.filters.push({
      kind: 'straightRight',
      args: [getLocator(locatorOrElement)],
    })
    return this
  }

  /**
   * Look for elements near the root element passed in
   * @param {string|WebElement} locatorOrElement
   * @return {!RelativeBy} Return this object
   */
  near(locatorOrElement) {
    this.filters.push({
      kind: 'near',
      args: [getLocator(locatorOrElement)],
    })
    return this
  }

  /**
   * Returns a marshalled version of the {@link RelativeBy}
   * @return {!Object} Object representation of a {@link WebElement}
   *     that will be used in {@link #findElements}.
   */
  marshall() {
    return {
      relative: {
        root: this.root,
        filters: this.filters,
      },
    }
  }

  /** @override */
  toString() {
    // The static By.name() overrides this.constructor.name.  Shame...
    return `RelativeBy(${JSON.stringify(this.marshall())})`
  }
}

/**
 * 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 || locator instanceof RelativeBy || typeof locator === 'function') {
    return locator
  }

  if (
    locator &&
    typeof locator === 'object' &&
    typeof locator.using === 'string' &&
    typeof locator.value === 'string'
  ) {
    return new By(locator.using, locator.value)
  }

  for (let key in locator) {
    if (Object.prototype.hasOwnProperty.call(locator, key) && Object.prototype.hasOwnProperty.call(By, key)) {
      return By[key](locator[key])
    }
  }
  throw new TypeError('Invalid locator')
}

// PUBLIC API

module.exports = {
  By,
  RelativeBy,
  withTagName,
  locateWith,
  escapeCss,
  checkedLocator: check,
}