browsertime 26.3.1 → 27.0.0

package/lib/core/engine/command/mouse/mouseMove.js

@@ -1,5 +1,8 @@
 import { getLogger } from '@sitespeed.io/log';
 import { By, Origin } from 'selenium-webdriver';
+import webdriver from 'selenium-webdriver';
+import { executeCommand } from '../commandHelper.js';
+import { parseSelector } from '../selectorParser.js';
 const log = getLogger('browsertime.command.mouse');
 /**
  * Provides functionality to move the mouse cursor to elements or specific positions on a web page.
@@ -8,7 +11,11 @@ const log = getLogger('browsertime.command.mouse');
  * @hideconstructor
  */
 export class MouseMove {
-  constructor(browser) {
+  constructor(browser, options) {
+    /**
+     * @private
+     */
+    this.browser = browser;
     /**
      * @private
      */
@@ -17,9 +24,48 @@ export class MouseMove {
      * @private
      */
     this.actions = this.driver.actions({ async: true });
+    /**
+     * @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);
+    }
+  }
+
+  /**
+   * Moves the mouse cursor to an element using a unified selector string.
+   *
+   * @async
+   * @param {string} selector - The selector string. CSS by default, or use a prefix.
+   * @returns {Promise<void>}
+   * @throws {Error} Throws an error if the element is not found.
+   */
+  async run(selector) {
+    const { locator, description } = parseSelector(selector);
+    return executeCommand(
+      log,
+      'Could not move mouse to element %s',
+      description,
+      async () => {
+        const driver = this.browser.getDriver();
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        return this.actions.move({ origin: element }).perform();
+      },
+      this.browser
+    );
   }
 
   /**
+   * @private
    * Moves the mouse cursor to an element that matches a given XPath selector.
    *
    * @async
@@ -39,6 +85,7 @@ export class MouseMove {
   }
 
   /**
+   * @private
    * Moves the mouse cursor to an element that matches a given CSS selector.
    *
    * @async
@@ -58,6 +105,7 @@ export class MouseMove {
   }
 
   /**
+   * @private
    * Moves the mouse cursor to a specific position on the screen.
    *
    * @async
@@ -77,6 +125,7 @@ export class MouseMove {
   }
 
   /**
+   * @private
    * Moves the mouse cursor by an offset from its current position.
    *
    * @async

package/lib/core/engine/command/mouse/singleClick.js

@@ -1,5 +1,8 @@
 import { getLogger } from '@sitespeed.io/log';
 import { By } from 'selenium-webdriver';
+import webdriver from 'selenium-webdriver';
+import { executeCommand } from '../commandHelper.js';
+import { parseSelector } from '../selectorParser.js';
 const log = getLogger('browsertime.command.mouse');
 
 /**
@@ -9,7 +12,7 @@ const log = getLogger('browsertime.command.mouse');
  * @class
  */
 export class SingleClick {
-  constructor(browser, pageCompleteCheck) {
+  constructor(browser, pageCompleteCheck, options) {
     /**
      * @private
      */
@@ -22,9 +25,62 @@ export class SingleClick {
      * @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);
+    }
   }
 
   /**
+   * Performs a single click on an element using a unified selector string.
+   *
+   * @async
+   * @param {string} selector - The selector string. CSS by default, or use a prefix.
+   * @param {Object} [options] - Options for the click action.
+   * @param {boolean} [options.waitForNavigation=false] - If true, waits for page complete check.
+   * @returns {Promise<void>}
+   * @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 single click on element %s',
+      description,
+      async () => {
+        const driver = this.browser.getDriver();
+        await this._waitForElement(driver, locator);
+        const element = await driver.findElement(locator);
+        await this.actions.click(element).perform();
+        await this.actions.clear();
+        if (options.waitForNavigation) {
+          await this.browser.extraWait(this.pageCompleteCheck);
+        }
+      },
+      this.browser
+    );
+  }
+
+  /**
+   * @private
+   */
+  async _andWait(baseMethod, ...args) {
+    await baseMethod.apply(this, args);
+    return this.browser.extraWait(this.pageCompleteCheck);
+  }
+
+  /**
+   * @private
    * Performs a single mouse click on an element matching a given XPath selector.
    *
    * @async
@@ -34,25 +90,29 @@ export class SingleClick {
    * @throws {Error} Throws an error if the element is not found.
    */
   async byXpath(xpath, options) {
-    try {
-      const element = await this.browser
-        .getDriver()
-        .findElement(By.xpath(xpath));
-      await this.actions.click(element).perform();
-      if (options && 'wait' in options && options.wait === true) {
-        log.warn(
-          'Please use the byXpathAndWait method instead. We want to deprecate and remove the options from this method so we follow the same pattern everywhere.'
-        );
-        return this.browser.extraWait(this.pageCompleteCheck);
-      }
-    } catch (error) {
-      log.error('Could not single click on element with xpath %s', xpath);
-      log.verbose(error);
-      throw new Error('Could not single click on element with xpath ' + xpath);
-    }
+    return executeCommand(
+      log,
+      'Could not single click on element with xpath %s',
+      xpath,
+      async () => {
+        const element = await this.browser
+          .getDriver()
+          .findElement(By.xpath(xpath));
+        await this.actions.click(element).perform();
+        await this.actions.clear();
+        if (options && 'wait' in options && options.wait === true) {
+          log.warn(
+            'Please use the byXpathAndWait method instead. We want to deprecate and remove the options from this method so we follow the same pattern everywhere.'
+          );
+          return this.browser.extraWait(this.pageCompleteCheck);
+        }
+      },
+      this.browser
+    );
   }
 
   /**
+   * @private
    * Performs a single mouse click on an element matching a given XPath selector and wait for page complete check.
    *
    * @async
@@ -61,20 +121,11 @@ export class SingleClick {
    * @throws {Error} Throws an error if the element is not found.
    */
   async byXpathAndWait(xpath) {
-    try {
-      const element = await this.browser
-        .getDriver()
-        .findElement(By.xpath(xpath));
-      await this.actions.click(element).perform();
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not single click on element with xpath %s', xpath);
-      log.verbose(error);
-      throw new Error('Could not single click on element with xpath ' + xpath);
-    }
+    return this._andWait(this.byXpath, xpath);
   }
 
   /**
+   * @private
    * Performs a single mouse click on an element matching a given CSS selector.
    *
    * @async
@@ -84,27 +135,29 @@ export class SingleClick {
    * @throws {Error} Throws an error if the element is not found.
    */
   async bySelector(selector, options) {
-    try {
-      const element = await this.browser
-        .getDriver()
-        .findElement(By.css(selector));
-      await this.actions.click(element).perform();
-      if (options && 'wait' in options && options.wait === true) {
-        log.warn(
-          'Please use the bySelectorAndWait method instead. We want to deprecate and remove the options from this method so we follow the same pattern everywhere.'
-        );
-        return this.browser.extraWait(this.pageCompleteCheck);
-      }
-    } catch (error) {
-      log.error('Could not single click on element with selector %s', selector);
-      log.verbose(error);
-      throw new Error(
-        'Could not single click on element with selector ' + selector
-      );
-    }
+    return executeCommand(
+      log,
+      'Could not single click on element with selector %s',
+      selector,
+      async () => {
+        const element = await this.browser
+          .getDriver()
+          .findElement(By.css(selector));
+        await this.actions.click(element).perform();
+        await this.actions.clear();
+        if (options && 'wait' in options && options.wait === true) {
+          log.warn(
+            'Please use the bySelectorAndWait method instead. We want to deprecate and remove the options from this method so we follow the same pattern everywhere.'
+          );
+          return this.browser.extraWait(this.pageCompleteCheck);
+        }
+      },
+      this.browser
+    );
   }
 
   /**
+   * @private
    * Performs a single mouse click on an element matching a given CSS selector and waits on the page complete check.
    *
    * @async
@@ -113,22 +166,11 @@ export class SingleClick {
    * @throws {Error} Throws an error if the element is not found.
    */
   async bySelectorAndWait(selector) {
-    try {
-      const element = await this.browser
-        .getDriver()
-        .findElement(By.css(selector));
-      await this.actions.click(element).perform();
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not single click on element with selector %s', selector);
-      log.verbose(error);
-      throw new Error(
-        'Could not single click on element with selector ' + selector
-      );
-    }
+    return this._andWait(this.bySelector, selector);
   }
 
   /**
+   * @private
    * Performs a single mouse click at the current cursor position.
    *
    * @async
@@ -137,22 +179,26 @@ export class SingleClick {
    * @throws {Error} Throws an error if the single click action cannot be performed.
    */
   async atCursor(options) {
-    try {
-      await this.actions.click().perform();
-      if (options && 'wait' in options && options.wait === true) {
-        log.warn(
-          'Please use the atCursorAndWait method instead.We want to deprecate and remove the options from this method so we follow the same pattern everywhere.'
-        );
-        return this.browser.extraWait(this.pageCompleteCheck);
-      }
-    } catch (error) {
-      log.error('Could not perform single click');
-      log.verbose(error);
-      throw new Error('Could not perform single click');
-    }
+    return executeCommand(
+      log,
+      'Could not perform single click',
+      undefined,
+      async () => {
+        await this.actions.click().perform();
+        await this.actions.clear();
+        if (options && 'wait' in options && options.wait === true) {
+          log.warn(
+            'Please use the atCursorAndWait method instead.We want to deprecate and remove the options from this method so we follow the same pattern everywhere.'
+          );
+          return this.browser.extraWait(this.pageCompleteCheck);
+        }
+      },
+      this.browser
+    );
   }
 
   /**
+   * @private
    * Performs a single mouse click at the current cursor position and waits on the
    * page complete check.
    *
@@ -161,17 +207,11 @@ export class SingleClick {
    * @throws {Error} Throws an error if the single click action cannot be performed.
    */
   async atCursorAndWait() {
-    try {
-      await this.actions.click().perform();
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not perform single click');
-      log.verbose(error);
-      throw new Error('Could not perform single click');
-    }
+    return this._andWait(this.atCursor);
   }
 
   /**
+   * @private
    * Clicks on a link whose visible text matches the given string.
    *
    * @async
@@ -180,17 +220,17 @@ export class SingleClick {
    * @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
+    );
   }
 
   /**
+   * @private
    * Clicks on a link whose visible text matches the given string and waits on the opage complete check.
    *
    * @async
@@ -199,17 +239,17 @@ export class SingleClick {
    * @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 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.byXpathAndWait(`//a[text()='${text}']`),
+      this.browser
+    );
   }
 
   /**
+   * @private
    * Clicks on a link whose visible text contains the given substring.
    *
    * @async
@@ -218,17 +258,17 @@ export class SingleClick {
    * @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
+    );
   }
 
   /**
+   * @private
    * Clicks on a link whose visible text contains the given substring and waits on the
    * page complete check.
    *
@@ -238,17 +278,17 @@ export class SingleClick {
    * @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
+    );
   }
 
   /**
+   * @private
    * Clicks on a element with a specific id.
    *
    * @async
@@ -257,17 +297,21 @@ export class SingleClick {
    * @throws {Error} Throws an error if the id is not found.
    */
   async byId(id) {
-    try {
-      const element = await this.browser.getDriver().findElement(By.id(id));
-      return this.actions.click(element).perform();
-    } catch (error) {
-      log.error('Could not find the element with id %s', id);
-      log.verbose(error);
-      throw new Error('Could not the element with id ' + id);
-    }
+    return executeCommand(
+      log,
+      'Could not find the element with id %s',
+      id,
+      async () => {
+        const element = await this.browser.getDriver().findElement(By.id(id));
+        await this.actions.click(element).perform();
+        return this.actions.clear();
+      },
+      this.browser
+    );
   }
 
   /**
+   * @private
    * Clicks on a element with a specific id and wait on the page complete check
    *
    * @async
@@ -276,14 +320,6 @@ export class SingleClick {
    * @throws {Error} Throws an error if the id is not found.
    */
   async byIdAndWait(id) {
-    try {
-      const element = await this.browser.getDriver().findElement(By.id(id));
-      await this.actions.click(element).perform();
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not find the element with id %s', id);
-      log.verbose(error);
-      throw new Error('Could not the element with id ' + id);
-    }
+    return this._andWait(this.byId, id);
   }
 }

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

@@ -25,7 +25,7 @@ export class Navigation {
    *
    * @async
    * @example await commands.navigation.back();
-   * @param {Object} [options] - Additional options for navigation. Set {wait:true} to wait for the page complete check to run.
+   * @param {Object} [options] - Additional options for navigation. Set {waitForNavigation:true} to wait for the page complete check to run.
    * @returns {Promise<void>} A promise that resolves when the navigation action is completed.
    * @throws {Error} Throws an error if navigation fails.
    */
@@ -33,7 +33,7 @@ export class Navigation {
     const driver = this.browser.getDriver();
     try {
       await driver.navigate().back();
-      if (options && 'wait' in options && options.wait == true) {
+      if (options && (options.waitForNavigation || options.wait)) {
         return this.browser.extraWait(this.pageCompleteCheck);
       }
     } catch (error) {
@@ -48,7 +48,7 @@ export class Navigation {
    *
    * @async
    * @example await commands.navigation.forward();
-   * @param {Object} [options] - Additional options for navigation. Set {wait:true} to wait for the page complete check to run.
+   * @param {Object} [options] - Additional options for navigation. Set {waitForNavigation:true} to wait for the page complete check to run.
    * @returns {Promise<void>} A promise that resolves when the navigation action is completed.
    * @throws {Error} Throws an error if navigation fails.
    */
@@ -56,7 +56,7 @@ export class Navigation {
     const driver = this.browser.getDriver();
     try {
       await driver.navigate().forward();
-      if (options && 'wait' in options && options.wait === true) {
+      if (options && (options.waitForNavigation || options.wait)) {
         return this.browser.extraWait(this.pageCompleteCheck);
       }
     } catch (error) {
@@ -71,7 +71,7 @@ export class Navigation {
    *
    * @async
    * @example await commands.navigation.refresh();
-   * @param {Object} [options] - Additional options for refresh action. Set {wait:true} to wait for the page complete check to run.
+   * @param {Object} [options] - Additional options for refresh action. Set {waitForNavigation:true} to wait for the page complete check to run.
    * @returns {Promise<void>} A promise that resolves when the page has been refreshed.
    * @throws {Error} Throws an error if refreshing the page fails.
    */
@@ -79,7 +79,7 @@ export class Navigation {
     const driver = this.browser.getDriver();
     try {
       await driver.navigate().refresh();
-      if (options && 'wait' in options && options.wait === true) {
+      if (options && (options.waitForNavigation || options.wait)) {
         return this.browser.extraWait(this.pageCompleteCheck);
       }
     } catch (error) {