browsertime 20.0.0 → 21.1.0

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

@@ -1,18 +1,37 @@
 import intel from 'intel';
 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. Uses Seleniums Action API.
+ *
+ * @hideconstructor
+ * @class
+ */
 export class SingleClick {
   constructor(browser, pageCompleteCheck) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.actions = this.browser.getDriver().actions({ async: true });
+    /**
+     * @private
+     */
     this.pageCompleteCheck = pageCompleteCheck;
   }
 
   /**
-   * Perform mouse single click on an element matches a XPath selector.
-   * @param {string} xpath
-   * @returns {Promise} Promise object represents when the element has been clicked.
-   * @throws Will throw an error if the element is not found.
+   * Performs a single mouse click on an element matching a given XPath selector.
+   *
+   * @async
+   * @param {string} xpath - The XPath selector of the element to click.
+   * @param {Object} [options] - Additional options for the click action.
+   * @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 byXpath(xpath, options) {
     try {
@@ -21,6 +40,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) {
@@ -31,10 +53,35 @@ export class SingleClick {
   }
 
   /**
-   * Perform mouse single click on an element matches a CSS selector.
-   * @param {string} selector
-   * @returns {Promise} Promise object represents when the element has been clicked.
-   * @throws Will throw an error if the element is not found.
+   * 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.
+   *
+   * @async
+   * @param {string} selector - The CSS selector of the element to click.
+   * @param {Object} [options] - Additional options for the click action.
+   * @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 bySelector(selector, options) {
     try {
@@ -43,6 +90,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) {
@@ -55,15 +105,44 @@ export class SingleClick {
   }
 
   /**
-   * Perform mouse single click at the cursor's position.
-   * @param {string} xpath
-   * @returns {Promise} Promise object represents when double click occurs.
-   * @throws Will throw an error if double click cannot be performed.
+   * 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.
+   *
+   * @async
+   * @param {Object} [options] - Additional options for the click action.
+   * @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 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) {
@@ -72,4 +151,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);
+    }
+  }
 }

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

@@ -1,14 +1,32 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.navigation');
 
+/**
+ * Provides functionality to control browser navigation such as back, forward, and refresh actions.
+ *
+ * @class
+ * @hideconstructor
+ */
+
 export class Navigation {
   constructor(browser, pageCompleteCheck) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.pageCompleteCheck = pageCompleteCheck;
   }
 
   /**
-   * Navigate backward in history
+   * Navigates backward in the browser's history.
+   *
+   * @async
+   * @param {Object} [options] - Additional options for navigation. Set {wait: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.
    */
   async back(options) {
     const driver = this.browser.getDriver();
@@ -25,7 +43,12 @@ export class Navigation {
   }
 
   /**
-   * Navigate forward in history
+   * Navigates forward in the browser's history.
+   *
+   * @async
+   * @param {Object} [options] - Additional options for navigation. Set {wait: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.
    */
   async forward(options) {
     const driver = this.browser.getDriver();
@@ -42,7 +65,12 @@ export class Navigation {
   }
 
   /**
-   * Refresh page
+   * Refreshes the current page.
+   *
+   * @async
+   * @param {Object} [options] - Additional options for refresh action. Set {wait: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.
    */
   async refresh(options) {
     const driver = this.browser.getDriver();

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

@@ -1,11 +1,44 @@
+import intel from 'intel';
+const log = intel.getLogger('browsertime.command.screenshot');
+
+/**
+ * Take a screenshot. The screenshot will be stored to disk,
+ * named by the name provided to the take function.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Screenshot {
   constructor(screenshotManager, browser, index) {
+    /**
+     * @private
+     */
     this.screenshotManager = screenshotManager;
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.index = index;
   }
 
+  /**
+   * Takes a screenshot and saves it using the screenshot manager.
+   *
+   * @async
+   * @example async commands.screenshot.take('my_startpage');
+   * @param {string} name The name to assign to the screenshot file.
+   * @throws {Error} Throws an error if the name parameter is not provided.
+   * @returns {Promise<Object>} A promise that resolves with the screenshot details.
+   */
+
   async take(name) {
+    if (!name) {
+      log.error('Missing name for the screenshot');
+      throw new Error(`Could not store screenshot for missing name`);
+    }
     const url = await this.browser
       .getDriver()
       .executeScript('return document.documentURI;');

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

@@ -1,16 +1,32 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.scroll');
 const delay = ms => new Promise(res => setTimeout(res, ms));
+
+/**
+ * Provides functionality to control page scrolling in the browser.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Scroll {
   constructor(browser, options) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.options = options;
   }
 
   /**
-   * Scroll the page by the specified pixels.
-   * @param {number} X pixels and Y pixels
-   * @returns {Promise} Promise object represents when scrolling the page has been
+   * Scrolls the page by the specified number of pixels.
+   *
+   * @async
+   * @param {number} Xpixels - The number of pixels to scroll horizontally.
+   * @param {number} Ypixels - The number of pixels to scroll vertically.
+   * @returns {Promise<void>} A promise that resolves when the scrolling action is completed.
    */
   async byPixels(Xpixels, Ypixels) {
     const script = `window.scrollBy(${Xpixels}, ${Ypixels});`;
@@ -18,10 +34,12 @@ export class Scroll {
   }
 
   /**
-   * Scroll the page by the specified lines.  Only supported by Firefox.
-   * @param {number} Lines
-   * @returns {Promise} Promise object represents when scrolling the page has been finished.
-   * @throws Will throw an error if window.scrollByLines generates an error.
+   * Scrolls the page by the specified number of lines. This method is only supported in Firefox.
+   *
+   * @async
+   * @param {number} lines - The number of lines to scroll.
+   * @returns {Promise<void>} A promise that resolves when the scrolling action is completed.
+   * @throws {Error} Throws an error if not used in Firefox.
    */
   async byLines(lines) {
     if (this.options.browser !== 'firefox') {
@@ -38,9 +56,11 @@ export class Scroll {
   }
 
   /**
-   * Scroll the page by the specified pages.
-   * @param {number} Pages
-   * @returns {Promise} Promise object represents when scrolling the page has been finished.
+   * Scrolls the page by the specified number of pages.
+   *
+   * @async
+   * @param {number} pages - The number of pages to scroll.
+   * @returns {Promise<void>} A promise that resolves when the scrolling action is completed.
    */
   async byPages(pages) {
     if (this.options.browser === 'firefox') {
@@ -55,9 +75,11 @@ export class Scroll {
   }
 
   /**
-   * Scroll to the bottom of the page. Will scroll page by page and wait the delayTime between each scroll. Default delay time is 250 ms
-   * @param {number} delayTime
-   * @returns {Promise} Promise object represents when scrolling the page has been finished.
+   * Scrolls to the bottom of the page, scrolling page by page with a delay between each scroll.
+   *
+   * @async
+   * @param {number} [delayTime=250] - The delay time in milliseconds between each scroll.
+   * @returns {Promise<void>} A promise that resolves when the scrolling to the bottom is completed.
    */
   async toBottom(delayTime = 250) {
     const pages = await this.browser.runScript(

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

@@ -1,18 +1,28 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.select');
 
+/**
+ * Provides functionality to interact with `<select>` elements on a web page.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Select {
   constructor(browser) {
+    /**
+     * @private
+     */
     this.browser = browser;
   }
 
   /**
-   * Select value of a select by the selects id
-   * @param {string} selectId The id of the select
-   * @param {string} value The value of the option you want to set
-   * @returns {Promise} Promise object represents when the option has been
-   * set to the element
-   * @throws Will throw an error if the select is not found
+   * Selects an option in a `<select>` element by its ID and the value of the option.
+   *
+   * @async
+   * @param {string} selectId - The ID of the `<select>` element.
+   * @param {string} value - The value of the option to select.
+   * @returns {Promise<void>} A promise that resolves when the option is selected.
+   * @throws {Error} Throws an error if the `<select>` element is not found.
    */
   async selectByIdAndValue(selectId, value) {
     try {
@@ -26,12 +36,13 @@ export class Select {
   }
 
   /**
-   * Select value of a select by the selects name
-   * @param {string} selectName The name of the select
-   * @param {string} value The value of the option you want to set
-   * @returns {Promise} Promise object represents when the option has been
-   * set to the element
-   * @throws Will throw an error if the select is not found
+   * Selects an option in a `<select>` element by its name and the value of the option.
+   *
+   * @async
+   * @param {string} selectName - The name of the `<select>` element.
+   * @param {string} value - The value of the option to select.
+   * @returns {Promise<void>} A promise that resolves when the option is selected.
+   * @throws {Error} Throws an error if the `<select>` element is not found.
    */
   async selectByNameAndValue(selectName, value) {
     try {
@@ -47,12 +58,13 @@ export class Select {
   }
 
   /**
-   * Select value of a select index and  by the selects id
-   * @param {string} selectId The id of the select
-   * @param {number} index the index of the option you want to set
-   * @returns {Promise} Promise object represents when the option has been
-   * set to the element
-   * @throws Will throw an error if the select is not found
+   * Selects an option in a `<select>` element by its ID and the index of the option.
+   *
+   * @async
+   * @param {string} selectId - The ID of the `<select>` element.
+   * @param {number} index - The index of the option to select.
+   * @returns {Promise<void>} A promise that resolves when the option is selected.
+   * @throws {Error} Throws an error if the `<select>` element is not found.
    */
   async selectByIdAndIndex(selectId, index) {
     try {
@@ -70,12 +82,13 @@ export class Select {
   }
 
   /**
-   * Select value of a select index and by the selects name
-   * @param {string} selectName - the name of the select
-   * @param {number} index - the index of the option you want to set
-   * @returns {Promise} Promise object represents when the option has been
-   * set to the element
-   * @throws Will throw an error if the select is not found
+   * Selects an option in a `<select>` element by its name and the index of the option.
+   *
+   * @async
+   * @param {string} selectName - The name of the `<select>` element.
+   * @param {number} index - The index of the option to select.
+   * @returns {Promise<void>} A promise that resolves when the option is selected.
+   * @throws {Error} Throws an error if the `<select>` element is not found.
    */
   async selectByNameAndIndex(selectName, index) {
     try {
@@ -93,10 +106,12 @@ export class Select {
   }
 
   /**
-   * Deselect all options in a select.
-   * @param {string} selectId
-   * @returns {Promise} Promise object represents when options been deselected
-   * @throws Will throw an error if the select is not found
+   * Deselects all options in a `<select>` element by its ID.
+   *
+   * @async
+   * @param {string} selectId - The ID of the `<select>` element.
+   * @returns {Promise<void>} A promise that resolves when all options are deselected.
+   * @throws {Error} Throws an error if the `<select>` element is not found.
    */
   async deselectById(selectId) {
     try {
@@ -111,10 +126,12 @@ export class Select {
   }
 
   /**
-   * Get all option values in a select.
-   * @param {string} selectId - the id of the select.
-   * @returns {Promise} Promise object tha will return an array with the values of the select
-   * @throws Will throw an error if the select is not found
+   * Retrieves all option values in a `<select>` element by its ID.
+   *
+   * @async
+   * @param {string} selectId - The ID of the `<select>` element.
+   * @returns {Promise<string[]>} A promise that resolves with an array of the values of the options.
+   * @throws {Error} Throws an error if the `<select>` element is not found.
    */
   async getValuesById(selectId) {
     const script = `const select = document.getElementById('${selectId}');
@@ -136,10 +153,12 @@ export class Select {
   }
 
   /**
-   * Get the selected option value in a select.
-   * @param {select} selectId the id of the select.
-   * @returns {Promise} Promise object tha will return the value of the selected option.
-   * @throws Will throw an error if the select is not found.
+   * Retrieves the value of the selected option in a `<select>` element by its ID.
+   *
+   * @async
+   * @param {string} selectId - The ID of the `<select>` element.
+   * @returns {Promise<string>} A promise that resolves with the value of the selected option.
+   * @throws {Error} Throws an error if the `<select>` element is not found.
    */
   async getSelectedValueById(selectId) {
     try {