Merge branch 'main' into remove-firefox-profile

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Browsertime changelog (we do [semantic versioning](https://semver.org))
 
+## UNRELEASED
+### Added
+* Upgraded to [Geckodriver 0.34.0](https://github.com/mozilla/geckodriver/releases/tag/v0.34.0) [#2049](https://github.com/sitespeedio/browsertime/pull/2049).
+* Collect CPU consumption for Firefox. Turn that on with `--firefox.powerConsumption true` and including `power` as a geckoProfilerParams.features [#2046](https://github.com/sitespeedio/browsertime/pull/2046).
+
+### Fixed
+* Make sure the visual metrics files are inlcuded in the Docker file [#2053](https://github.com/sitespeedio/browsertime/pull/2053).
+* Removing QVH from the npm package (used for iPhone video recording but not working) [#2051](https://github.com/sitespeedio/browsertime/pull/2051)
+* Removing visual metrics test images from the npm package [#2050](https://github.com/sitespeedio/browsertime/pull/2050).
+* Removed the Chromedriver fix that was needed when Chrome for testing broke testing on Chrome :D [#2045](https://github.com/sitespeedio/browsertime/pull/2045).
+* Refactor of commands/context object to prepare for supporting JSDoc and a little TypeScript to add code completion/IntelliSense in editors [#2047](https://github.com/sitespeedio/browsertime/pull/2047).
+* Updated documentation for scripting with better JSDoc [#204](https://github.com/sitespeedio/browsertime/pull/2048).
+
 ## 20.0.0 - 2023-12-22
 
 ### Breaking

lib/core/engine/command/android.js

@@ -5,6 +5,7 @@ const log = intel.getLogger('browsertime.command.android');
  * Provides functionality to interact with an Android device through shell commands.
  *
  * @class
+ * @see https://www.sitespeed.io/documentation/sitespeed.io/mobile-phones/#test-on-android
  */
 export class AndroidCommand {
   constructor(options) {

lib/core/engine/command/chromeDevToolsProtocol.js

@@ -4,9 +4,9 @@ const log = intel.getLogger('browsertime.command.devtoolsprotocol');
 /**
  * Manages interactions with the Chrome DevTools Protocol for Chrome and Edge browsers.
  * Allows sending commands and setting up event listeners via the protocol.
- * See https://chromedevtools.github.io/devtools-protocol/
  *
  * @class
+ * @see https://chromedevtools.github.io/devtools-protocol/
  */
 export class ChromeDevelopmentToolsProtocol {
   constructor(engineDelegate, browserName) {

lib/core/engine/command/click.js

@@ -11,8 +11,8 @@ function addClick(js) {
 }
 
 /**
- * Provides functionality to perform click actions on elements in a web page using various selectors.
- *
+ * Provides functionality to perform click  on elements in a web page using various selectors.
+ * This implemention gets the elemnt and adds .click(); to it.
  * @class
  */
 export class Click {

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

@@ -3,7 +3,7 @@ import { By } from 'selenium-webdriver';
 const log = intel.getLogger('browsertime.command.mouse');
 
 /**
- * Provides functionality to perform a single click action on elements or at specific positions in a web page.
+ * Provides functionality to perform a single click action on elements or at specific positions in a web page. Uses Seleniums Action API.
  *
  * @class
  */
@@ -39,6 +39,9 @@ export class SingleClick {
         .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) {
@@ -48,6 +51,28 @@ export class SingleClick {
     }
   }
 
+  /**
+   * Performs a single mouse click on an element matching a given XPath selector and wait for page complete check.
+   *
+   * @async
+   * @param {string} xpath - The XPath selector of the element to click.
+   * @returns {Promise<void>} A promise that resolves when the single click action is performed.
+   * @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);
+    }
+  }
+
   /**
    * Performs a single mouse click on an element matching a given CSS selector.
    *
@@ -64,6 +89,9 @@ export class SingleClick {
         .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) {
@@ -75,6 +103,30 @@ export class SingleClick {
     }
   }
 
+  /**
+   * Performs a single mouse click on an element matching a given CSS selector and waits on the page complete check.
+   *
+   * @async
+   * @param {string} selector - The CSS selector of the element to click.
+   * @returns {Promise<void>} A promise that resolves when the single click action is performed.
+   * @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
+      );
+    }
+  }
+
   /**
    * Performs a single mouse click at the current cursor position.
    *
@@ -87,6 +139,9 @@ export class SingleClick {
     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) {
@@ -95,4 +150,100 @@ export class SingleClick {
       throw new Error('Could not perform single click');
     }
   }
+
+  /**
+   * Performs a single mouse click at the current cursor position and waits on the
+   * page complete check.
+   *
+   * @async
+   * @returns {Promise<void>} A promise that resolves when the single click occurs.
+   * @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');
+    }
+  }
+
+  /**
+   * Clicks on a link whose visible text matches the given string.
+   *
+   * @async
+   * @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);
+    }
+  }
+
+  /**
+   * Clicks on a link whose visible text matches the given string and waits on the opage complete check.
+   *
+   * @async
+   * @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 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);
+    }
+  }
+
+  /**
+   * Clicks on a link whose visible text contains the given substring.
+   *
+   * @async
+   * @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);
+    }
+  }
+
+  /**
+   * Clicks on a link whose visible text contains the given substring and waits on the
+   * page complete checl.
+   *
+   * @async
+   * @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 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);
+    }
+  }
 }

lib/core/engine/context.js

@@ -64,6 +64,7 @@ export class Context {
 
     /**
      * Get raw Selenium functionality.
+     * @see https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index.html
      * @type {{webdriver: WebDriverClass, driver: WebDriverInstance}}
      */
     this.selenium = {