browsertime 26.3.1 → 27.0.0

package/lib/core/engine/command/click.js

@@ -1,23 +1,20 @@
 import { getLogger } from '@sitespeed.io/log';
+import webdriver, { By } from 'selenium-webdriver';
+import { executeCommand } from './commandHelper.js';
+import { parseSelector } from './selectorParser.js';
 const log = getLogger('browsertime.command.click');
 
-function addClick(js) {
-  const trimmed = js.trim();
-  let script = `${trimmed}.click();`;
-  if (trimmed.endsWith(';')) {
-    script = `${trimmed.slice(0, -1)}.click();`;
-  }
-  return script;
-}
-
 /**
  * Provides functionality to perform click actions on elements in a web page using various selectors.
+ * Uses the Selenium Actions API to generate real OS-level mouse events, which means
+ * the element must be visible and interactable. If you need to click a hidden element,
+ * use {@link JavaScript#run commands.js.run} to trigger a JavaScript click instead.
  *
  * @class
  * @hideconstructor
  */
 export class Click {
-  constructor(browser, pageCompleteCheck) {
+  constructor(browser, pageCompleteCheck, options) {
     /**
      * @private
      */
@@ -26,296 +23,399 @@ export class Click {
      * @private
      */
     this.pageCompleteCheck = pageCompleteCheck;
+    /**
+     * @private
+     */
+    this.options = options;
+  }
+
+  /**
+   * @private
+   */
+  async _waitForElement(driver, locator) {
+    const timeout = this.options?.timeouts?.elementWait ?? 0;
+    if (timeout > 0) {
+      await driver.wait(webdriver.until.elementLocated(locator), timeout);
+    }
+  }
+
+  /**
+   * @private
+   */
+  async _andWait(baseMethod, ...args) {
+    log.info(
+      'The AndWait methods are deprecated. Use commands.click(selector, { wait: true }) instead.'
+    );
+    await baseMethod.apply(this, args);
+    return this.browser.extraWait(this.pageCompleteCheck);
+  }
+
+  /**
+   * @private
+   */
+  async _clickElement(element) {
+    const driver = this.browser.getDriver();
+    await driver.actions({ async: true }).click(element).perform();
+    return driver.actions().clear();
+  }
+
+  /**
+   * Clicks on an element using a unified selector string.
+   * Supports CSS selectors (default), and prefix-based strategies:
+   * 'id:myId', 'xpath://button', 'text:Submit', 'link:Click here', 'name:email', 'class:btn'.
+   *
+   * @async
+   * @param {string} selector - The selector string. CSS by default, or use a prefix like 'id:', 'xpath:', 'text:', 'link:', 'name:', 'class:'.
+   * @param {Object} [options] - Options for the click action.
+   * @param {boolean} [options.waitForNavigation=false] - If true, waits for the page complete check after clicking.
+   * @returns {Promise<void>} A promise that resolves when the click action is performed.
+   * @throws {Error} Throws an error if the element is not found.
+   */
+  async run(selector, options = {}) {
+    const { locator, description } = parseSelector(selector);
+    return executeCommand(
+      log,
+      'Could not find element by %s',
+      description,
+      async () => {
+        const driver = this.browser.getDriver();
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        await this._clickElement(element);
+        if (options.waitForNavigation) {
+          await this.browser.extraWait(this.pageCompleteCheck);
+        }
+      },
+      this.browser
+    );
   }
 
   /**
    * Clicks on an element identified by its class name.
    *
    * @async
+   * @private
    * @param {string} className - The class name of the element to click.
    * @returns {Promise<void>} A promise that resolves when the click action is performed.
    * @throws {Error} Throws an error if the element is not found.
    */
   async byClassName(className) {
-    try {
-      const script = `document.getElementsByClassName('${className}')[0].click();`;
-      await this.browser.runScript(script, 'CUSTOM');
-    } catch (error) {
-      log.error('Could not find element by class name %s', className);
-      log.verbose(error);
-      throw new Error('Could not find element by class name ' + className);
-    }
+    return executeCommand(
+      log,
+      'Could not find element by class name %s',
+      className,
+      async () => {
+        const driver = this.browser.getDriver();
+        const locator = By.className(className);
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        return this._clickElement(element);
+      },
+      this.browser
+    );
   }
 
   /**
    * Clicks on an element identified by its class name and waits for the page complete check to finish.
    *
    * @async
+   * @private
    * @param {string} className - The class name of the element to click.
    * @returns {Promise<void>} A promise that resolves when the click action and page complete check are finished.
    * @throws {Error} Throws an error if the element is not found.
    */
   async byClassNameAndWait(className) {
-    try {
-      const script = `document.getElementsByClassName('${className}')[0].click();`;
-      await this.browser.runScript(script, 'CUSTOM');
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not find element by class name %s', className);
-      log.verbose(error);
-      throw new Error('Could not find element by class name ' + className);
-    }
+    return this._andWait(this.byClassName, className);
   }
 
   /**
    * Clicks on a link whose visible text matches the given string.
    *
    * @async
+   * @private
    * @param {string} text - The visible text of the link to click.
    * @returns {Promise<void>} A promise that resolves when the click action is performed.
    * @throws {Error} Throws an error if the link is not found.
    */
   async byLinkText(text) {
-    try {
-      const xpath = `//a[text()='${text}']`;
-      return this.byXpath(xpath);
-    } catch (error) {
-      log.error('Could not find link by text %s', text);
-      log.verbose(error);
-      throw new Error('Could not find link by text ' + text);
-    }
+    return executeCommand(
+      log,
+      'Could not find link by text %s',
+      text,
+      () => this.byXpath(`//a[text()='${text}']`),
+      this.browser
+    );
   }
 
   /**
    * Clicks on a link whose visible text matches the given string and waits for the page complete check to finish.
    *
    * @async
+   * @private
    * @param {string} text - The visible text of the link to click.
    * @returns {Promise<void>} A promise that resolves when the click action and page complete check are finished.
    * @throws {Error} Throws an error if the link is not found.
    */
   async byLinkTextAndWait(text) {
-    try {
-      const xpath = `//a[text()='${text}']`;
-      return this.byXpathAndWait(xpath);
-    } catch (error) {
-      log.error('Could not find link with text %s', text);
-      log.verbose(error);
-      throw new Error('Could not find link by text ' + text);
-    }
+    return executeCommand(
+      log,
+      'Could not find link by text %s',
+      text,
+      () => this.byXpathAndWait(`//a[text()='${text}']`),
+      this.browser
+    );
   }
 
   /**
    * Clicks on a link whose visible text contains the given substring.
    *
    * @async
+   * @private
    * @param {string} text - The substring of the visible text of the link to click.
    * @returns {Promise<void>} A promise that resolves when the click action is performed.
    * @throws {Error} Throws an error if the link is not found.
    */
   async byPartialLinkText(text) {
-    try {
-      const xpath = `//a[contains(text(),'${text}')]`;
-      return this.byXpath(xpath);
-    } catch (error) {
-      log.error('Could not find link by partial text %s', text);
-      log.verbose(error);
-      throw new Error('Could not find link by partial text ' + text);
-    }
+    return executeCommand(
+      log,
+      'Could not find link by partial text %s',
+      text,
+      () => this.byXpath(`//a[contains(text(),'${text}')]`),
+      this.browser
+    );
   }
 
   /**
    * Clicks on a link whose visible text contains the given substring and waits for the page complete check to finish.
    *
    * @async
+   * @private
    * @param {string} text - The substring of the visible text of the link to click.
    * @returns {Promise<void>} A promise that resolves when the click action and page complete check are finished.
    * @throws {Error} Throws an error if the link is not found.
    */
   async byPartialLinkTextAndWait(text) {
-    try {
-      const xpath = `//a[contains(text(),'${text}')]`;
-      return this.byXpathAndWait(xpath);
-    } catch (error) {
-      log.error('Could not find link by partial text %s', text);
-      log.verbose(error);
-      throw new Error('Could not find link by partial text ' + text);
-    }
+    return executeCommand(
+      log,
+      'Could not find link by partial text %s',
+      text,
+      () => this.byXpathAndWait(`//a[contains(text(),'${text}')]`),
+      this.browser
+    );
+  }
+
+  /**
+   * Clicks on an element whose visible text matches the given string.
+   * This works on any element type, not just links.
+   *
+   * @async
+   * @private
+   * @param {string} text - The visible text of the element to click.
+   * @returns {Promise<void>} A promise that resolves when the click action is performed.
+   * @throws {Error} Throws an error if the element is not found.
+   */
+  async byText(text) {
+    return executeCommand(
+      log,
+      'Could not find element by text %s',
+      text,
+      () => this.byXpath(`//*[normalize-space(text())='${text}']`),
+      this.browser
+    );
+  }
+
+  /**
+   * Clicks on an element whose visible text matches the given string and waits for the page complete check to finish.
+   * This works on any element type, not just links.
+   *
+   * @async
+   * @private
+   * @param {string} text - The visible text of the element to click.
+   * @returns {Promise<void>} A promise that resolves when the click action and page complete check are finished.
+   * @throws {Error} Throws an error if the element is not found.
+   */
+  async byTextAndWait(text) {
+    return executeCommand(
+      log,
+      'Could not find element by text %s',
+      text,
+      () => this.byXpathAndWait(`//*[normalize-space(text())='${text}']`),
+      this.browser
+    );
   }
 
   /**
    * Clicks on an element that matches a given XPath selector.
    *
    * @async
+   * @private
    * @param {string} xpath - The XPath selector of the element to click.
    * @returns {Promise<void>} A promise that resolves when the click action is performed.
    * @throws {Error} Throws an error if the element is not found.
    */
   async byXpath(xpath) {
-    try {
-      // This is how Selenium do internally
-      const replaced = xpath.replaceAll('"', "'");
-      const script = `document.evaluate("${replaced}", document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue.click();`;
-      return this.browser.runScript(script, 'CUSTOM');
-    } catch (error) {
-      log.error('Could not find element by xpath %s', xpath);
-      log.verbose(error);
-      throw new Error('Could not find element by xpath ' + xpath);
-    }
+    return executeCommand(
+      log,
+      'Could not find element by xpath %s',
+      xpath,
+      async () => {
+        const driver = this.browser.getDriver();
+        const locator = By.xpath(xpath);
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        return this._clickElement(element);
+      },
+      this.browser
+    );
   }
   /**
    * Clicks on an element that matches a given XPath selector and waits for the page complete check to finish.
    *
    * @async
+   * @private
    * @param {string} xpath - The XPath selector of the element to click.
    * @returns {Promise<void>} A promise that resolves when the click action and page complete check are finished.
    * @throws {Error} Throws an error if the element is not found.
    */
   async byXpathAndWait(xpath) {
-    try {
-      // This is how Selenium do internally
-      const replaced = xpath.replaceAll('"', "'");
-      const script = `document.evaluate("${replaced}", document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue.click();`;
-      await this.browser.runScript(script, 'CUSTOM');
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not find element by xpath %s', xpath);
-      log.verbose(error);
-      throw new Error('Could not find element by xpath ' + xpath);
-    }
+    return this._andWait(this.byXpath, xpath);
   }
 
   /**
    * Clicks on an element located by evaluating a JavaScript expression.
    *
    * @async
+   * @private
    * @param {string} js - The JavaScript expression that evaluates to an element or list of elements.
    * @returns {Promise<void>} A promise that resolves when the click action is performed.
    * @throws {Error} Throws an error if the element is not found.
    */
   async byJs(js) {
-    try {
-      const script = addClick(js);
-      await this.browser.runScript(script, 'CUSTOM');
-    } catch (error) {
-      log.error('Could not find element by JavaScript %s', js);
-      log.verbose(error);
-      throw new Error('Could not find element by JavaScript ' + js);
-    }
+    return executeCommand(
+      log,
+      'Could not find element by JavaScript %s',
+      js,
+      async () => {
+        const trimmed = js.trim();
+        const script = trimmed.endsWith(';')
+          ? `return ${trimmed.slice(0, -1)};`
+          : `return ${trimmed};`;
+        const element = await this.browser.getDriver().executeScript(script);
+        return this._clickElement(element);
+      },
+      this.browser
+    );
   }
 
   /**
    * Clicks on an element located by evaluating a JavaScript expression and waits for the page complete check to finish.
    *
    * @async
+   * @private
    * @param {string} js - The JavaScript expression that evaluates to an element or list of elements.
    * @returns {Promise<void>} A promise that resolves when the click action and page complete check are finished.
    * @throws {Error} Throws an error if the element is not found.
    */
   async byJsAndWait(js) {
-    try {
-      const script = addClick(js);
-      await this.browser.runScript(script, 'CUSTOM');
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not find element by JavaScript %s', js);
-      log.verbose(error);
-      throw new Error('Could not find element by JavaScript ' + js);
-    }
+    return this._andWait(this.byJs, js);
   }
 
   /**
    * Clicks on an element located by its ID.
    *
    * @async
+   * @private
    * @param {string} id - The ID of the element to click.
    * @returns {Promise<void>} A promise that resolves when the click action is performed.
    * @throws {Error} Throws an error if the element is not found.
    */
   async byId(id) {
-    try {
-      const script = `document.getElementById('${id}').click();`;
-      await this.browser.runScript(script, 'CUSTOM');
-    } catch (error) {
-      log.error('Could not find element by id %s', id);
-      log.verbose(error);
-      throw new Error('Could not find element by id ' + id);
-    }
+    return executeCommand(
+      log,
+      'Could not find element by id %s',
+      id,
+      async () => {
+        const driver = this.browser.getDriver();
+        const locator = By.id(id);
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        return this._clickElement(element);
+      },
+      this.browser
+    );
   }
 
   /**
    * Clicks on an element located by its name attribute.
    *
    * @async
+   * @private
    * @param {string} name - The name attribute of the element to click.
    * @returns {Promise<void>} A promise that resolves when the click action is performed.
    * @throws {Error} Throws an error if the element is not found.
    */
   async byName(name) {
-    try {
-      const script = `document.querySelector("[name='${name}']").click()`;
-      await this.browser.runScript(script, 'CUSTOM');
-    } catch (error) {
-      log.error('Could not find element by name %s', name);
-      log.verbose(error);
-      throw new Error('Could not find element by name ' + name);
-    }
+    return executeCommand(
+      log,
+      'Could not find element by name %s',
+      name,
+      async () => {
+        const driver = this.browser.getDriver();
+        const locator = By.name(name);
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        return this._clickElement(element);
+      },
+      this.browser
+    );
   }
 
   /**
    * Click on link located by the ID attribute. Uses document.getElementById() to find the element. And wait for page complete check to finish.
+   * @private
    * @param {string} id
    * @returns {Promise<void>} Promise object represents when the element has been clicked and the pageCompleteCheck has finished.
    * @throws Will throw an error if the element is not found
    */
   async byIdAndWait(id) {
-    try {
-      const script = `document.getElementById('${id}').click();`;
-      await this.browser.runScript(script, 'CUSTOM');
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not find element by id %s', id);
-      log.verbose(error);
-      throw new Error('Could not find element by id ' + id);
-    }
+    return this._andWait(this.byId, id);
   }
 
   /**
    * Clicks on an element located by its CSS selector.
    *
    * @async
+   * @private
    * @param {string} selector - The CSS selector of the element to click.
    * @returns {Promise<void>} A promise that resolves when the click action is performed.
    * @throws {Error} Throws an error if the element is not found.
    */
   async bySelector(selector) {
-    try {
-      const script = `document.querySelector('${selector}').click();`;
-      await this.browser.runScript(script, 'CUSTOM');
-    } catch (error) {
-      log.error('Could not click using selector %s', selector);
-      log.verbose(error);
-      throw new Error('Could not click using selector ' + selector);
-    }
+    return executeCommand(
+      log,
+      'Could not click using selector %s',
+      selector,
+      async () => {
+        const driver = this.browser.getDriver();
+        const locator = By.css(selector);
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        return this._clickElement(element);
+      },
+      this.browser
+    );
   }
 
   /**
    * Clicks on an element located by its CSS selector and waits for the page complete check to finish.
    *
    * @async
+   * @private
    * @param {string} selector - The CSS selector of the element to click.
    * @returns {Promise<void>} A promise that resolves when the click action and page complete check are finished.
    * @throws {Error} Throws an error if the element is not found.
    */
   async bySelectorAndWait(selector) {
-    try {
-      const script = `document.querySelector('${selector}').click();`;
-      await this.browser.runScript(script, 'CUSTOM');
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not click using selector %s', selector);
-      log.verbose(error);
-      throw new Error('Could not click using selector ' + selector);
-    }
+    return this._andWait(this.bySelector, selector);
   }
 }

package/lib/core/engine/command/commandHelper.js

@@ -0,0 +1,45 @@
+/**
+ * Shared error handling wrapper for command methods.
+ *
+ * Most command methods follow the same try/catch pattern:
+ * log.error + log.verbose + throw new Error. This helper
+ * eliminates that boilerplate.
+ *
+ * @param {Object} log - The logger instance.
+ * @param {string} errorMessage - printf-style message (with %s placeholder).
+ * @param {string|undefined} identifier - Value to interpolate into the message, or undefined if none.
+ * @param {Function} fn - The async function to execute.
+ * @param {Object} [browser] - Optional browser instance. When provided, the current page URL is appended to the error message.
+ * @returns {Promise<*>} The return value of fn.
+ */
+export async function executeCommand(
+  log,
+  errorMessage,
+  identifier,
+  fn,
+  browser
+) {
+  try {
+    return await fn();
+  } catch (error) {
+    let url = '';
+    if (browser) {
+      try {
+        url = ` on ${await browser.getDriver().getCurrentUrl()}`;
+      } catch {
+        // If we can't get the URL, just skip it
+      }
+    }
+    const baseMessage =
+      identifier === undefined
+        ? errorMessage
+        : errorMessage.replace('%s', String(identifier));
+    if (identifier === undefined) {
+      log.error(errorMessage);
+    } else {
+      log.error(errorMessage, identifier);
+    }
+    log.verbose(error);
+    throw new Error(`${baseMessage}${url}`);
+  }
+}