browsertime 20.0.0 → 21.0.0

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

@@ -10,19 +10,31 @@ function addClick(js) {
   return script;
 }
 
+/**
+ * Provides functionality to perform click actions on elements in a web page using various selectors.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Click {
   constructor(browser, pageCompleteCheck) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.pageCompleteCheck = pageCompleteCheck;
   }
 
   /**
-   * Click on element that is found by specific class name.
-   * https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementsByClassName
-   * ;
-   * @param {string} className
-   * @returns {Promise} Promise object represents when the element has been clicked
-   * @throws Will throw an error if the element is not found
+   * Clicks on an element identified by its class name.
+   *
+   * @async
+   * @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 {
@@ -36,10 +48,12 @@ export class Click {
   }
 
   /**
-   * Click on element that is found by specific class name and wait for page load complete check to finish.
-   * @param {string} className
-   * @returns {Promise} Promise object represents when the element has been clicked and the pageCompleteCheck has finisshed.
-   * @throws Will throw an error if the element is not found
+   * Clicks on an element identified by its class name and waits for the page complete check to finish.
+   *
+   * @async
+   * @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 {
@@ -54,10 +68,12 @@ export class Click {
   }
 
   /**
-   * Click on link whose visible text matches the given string.
-   * @param {string} text
-   * @returns {Promise} Promise object represents when the element has been clicked
-   * @throws Will throw an error if the element is not found
+   * 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 {
@@ -71,10 +87,12 @@ export class Click {
   }
 
   /**
-   * Click on link whose visible text matches the given string and wait for pageCompleteCheck to finish.
-   * @param {string} text
-   * @returns {Promise} 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
+   * Clicks on a link whose visible text matches the given string and waits for the page complete check to finish.
+   *
+   * @async
+   * @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 {
@@ -88,10 +106,12 @@ export class Click {
   }
 
   /**
-   * Click on link whose visible text contains the given substring.
-   * @param {string} text
-   * @returns {Promise} Promise object represents when the element has been clicked
-   * @throws Will throw an error if the element is not found
+   * 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 {
@@ -105,10 +125,12 @@ export class Click {
   }
 
   /**
-   * Click on link whose visible text contains the given substring and wait for pageCompleteCheck to finish.
-   * @param {string} text
-   * @returns {Promise} 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
+   * Clicks on a link whose visible text contains the given substring and waits for the page complete check to finish.
+   *
+   * @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 and page complete check are finished.
+   * @throws {Error} Throws an error if the link is not found.
    */
   async byPartialLinkTextAndWait(text) {
     try {
@@ -120,11 +142,14 @@ export class Click {
       throw new Error('Could not find link by partial text ' + text);
     }
   }
+
   /**
-   * Click on link that 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
+   * Clicks on an element that matches a given XPath selector.
+   *
+   * @async
+   * @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 {
@@ -138,12 +163,13 @@ export class Click {
       throw new Error('Could not find element by xpath ' + xpath);
     }
   }
-  /**.
-   * Click on link that matches a XPath selector and wait for page load complete check to finish
+  /**
+   * Clicks on an element that matches a given XPath selector and waits for the page complete check to finish.
    *
-   * @param {string} xpath
-   * @returns {Promise} 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
+   * @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 {
@@ -160,10 +186,12 @@ export class Click {
   }
 
   /**
-   * Click on a link located by evaluating a JavaScript expression. The result of this expression must be an element or list of elements.
-   *  @param {string} js
-   * @returns {Promise} Promise object represents when the element has been clicked
-   * @throws Will throw an error if the element is not found
+   * Clicks on an element located by evaluating a JavaScript expression.
+   *
+   * @async
+   * @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 {
@@ -177,10 +205,12 @@ export class Click {
   }
 
   /**
-   * Click on a link located by evaluating a JavaScript expression. The result of this expression must be an element or list of elements. And wait for page complete check to finish.
-   *  @param {string} js
-   * @returns {Promise} 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
+   * Clicks on an element located by evaluating a JavaScript expression and waits for the page complete check to finish.
+   *
+   * @async
+   * @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 {
@@ -195,10 +225,12 @@ export class Click {
   }
 
   /**
-   * Click on link located by the ID attribute. Uses document.getElementById().
-   * @param {string} id
-   * @returns {Promise} Promise object represents when the element has been clicked
-   * @throws Will throw an error if the element is not found
+   * Clicks on an element located by its ID.
+   *
+   * @async
+   * @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 {
@@ -212,10 +244,12 @@ export class Click {
   }
 
   /**
-   * Click on element located by the name, Uses document.querySelector.
-   * @param {string} name the name of the element
-   * @returns {Promise} Promise object represents when the element has been clicked
-   * @throws Will throw an error if the element is not found
+   * Clicks on an element located by its name attribute.
+   *
+   * @async
+   * @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 {
@@ -231,7 +265,7 @@ export class Click {
   /**
    * Click on link located by the ID attribute. Uses document.getElementById() to find the element. And wait for page complete check to finish.
    * @param {string} id
-   * @returns {Promise} Promise object represents when the element has been clicked and the pageCompleteCheck has finished.
+   * @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) {
@@ -246,6 +280,14 @@ export class Click {
     }
   }
 
+  /**
+   * Clicks on an element located by its CSS selector.
+   *
+   * @async
+   * @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();`;
@@ -257,6 +299,14 @@ export class Click {
     }
   }
 
+  /**
+   * Clicks on an element located by its CSS selector and waits for the page complete check to finish.
+   *
+   * @async
+   * @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();`;

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

@@ -2,15 +2,32 @@ import intel from 'intel';
 const log = intel.getLogger('browsertime.command.debug');
 const delay = ms => new Promise(res => setTimeout(res, ms));
 
+/**
+ * Provides debugging capabilities within a browser automation script.
+ * It allows setting breakpoints to pause script execution and inspect the current state.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Debug {
   constructor(browser, options) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.options = options;
   }
 
   /**
-   * Add a breakpoint to script. The browser will wait at the breakpoint for user input.
-   * @returns {Promise} Promise object that is fulfilled when the user move on from the breakpoint.
+   * Adds a breakpoint to the script. The browser will pause at the breakpoint, waiting for user input to continue.
+   * This is useful for debugging and inspecting the browser state at a specific point in the script.
+   *
+   * @async
+   * @param {string} [name] - An optional name for the breakpoint for logging purposes.
+   * @returns {Promise<void>} A promise that resolves when the user chooses to continue from the breakpoint.
    */
   async breakpoint(name) {
     if (this.options.debug) {

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

@@ -0,0 +1,66 @@
+// We disable these because they are needed for code completion
+/* eslint no-unused-vars: "off" */
+import { By, WebElement } from 'selenium-webdriver';
+/**
+ * This class provides a way to get hokld of Seleniums WebElements.
+ * @class
+ * @hideconstructor
+ */
+export class Element {
+  constructor(browser) {
+    /**
+     * @private
+     */
+    this.driver = browser.getDriver();
+  }
+
+  /**
+   * Finds an element by its CSS selector.
+   *
+   * @param {string} name - The CSS selector of the element.
+   * @returns {Promise<WebElement>} A promise that resolves to the WebElement found.
+   */
+  async getByCss(name) {
+    return this.driver.findElement(By.css(name));
+  }
+
+  /**
+   * Finds an element by its ID.
+   *
+   * @param {string} id - The ID of the element.
+   * @returns {Promise<WebElement>} A promise that resolves to the WebElement found.
+   */
+  async getById(id) {
+    return this.driver.findElement(By.id(id));
+  }
+
+  /**
+   * Finds an element by its XPath.
+   *
+   * @param {string} xpath - The XPath query of the element.
+   * @returns {Promise<WebElement>} A promise that resolves to the WebElement found.
+   */
+  async getByXpath(xpath) {
+    return this.driver.findElement(By.xpath(xpath));
+  }
+
+  /**
+   * Finds an element by its class name.
+   *
+   * @param {string} className - The class name of the element.
+   * @returns {Promise<WebElement>} A promise that resolves to the WebElement found.
+   */
+  async getByClassName(className) {
+    return this.driver.findElement(By.className(className));
+  }
+
+  /**
+   * Finds an element by its name attribute.
+   *
+   * @param {string} name - The name attribute of the element.
+   * @returns {Promise<WebElement>} A promise that resolves to the WebElement found.
+   */
+  async getByName(name) {
+    return this.driver.findElement(By.name(name));
+  }
+}

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

@@ -1,14 +1,43 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.geckoprofiler');
+/**
+ * Manages the Gecko Profiler for profiling Firefox performance.
+ *
+ * @class
+ * @hideconstructor
+ */
+
 export class GeckoProfiler {
   constructor(GeckoProfiler, browser, index, options, result) {
+    /**
+     * @private
+     */
     this.GeckoProfiler = GeckoProfiler;
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.index = index;
+    /**
+     * @private
+     */
     this.options = options;
+    /**
+     * @private
+     */
     this.result = result;
   }
 
+  /**
+   * Starts the Gecko Profiler.
+   *
+   * @async
+   * @returns {Promise<void>} A promise that resolves when the profiler is started.
+   * @throws {Error} Throws an error if not running Firefox or if the configuration is not set for custom profiling.
+   */
   async start() {
     if (this.options.browser === 'firefox') {
       if (this.options.firefox.geckoProfilerRecordingType === 'custom') {
@@ -23,10 +52,21 @@ export class GeckoProfiler {
     }
   }
 
+  /**
+   * Stops the Gecko Profiler and processes the collected data.
+   *
+   * @async
+   * @returns {Promise<void>} A promise that resolves when the profiler is stopped and the data is processed.
+   * @throws {Error} Throws an error if not running Firefox or if custom profiling was not started.
+   */
   async stop() {
     if (this.options.browser === 'firefox') {
       if (this.options.firefox.geckoProfilerRecordingType === 'custom') {
-        return this.GeckoProfiler.stop(this.index, this.result[0].url);
+        return this.GeckoProfiler.stop(
+          this.index,
+          this.result[0].url,
+          this.result
+        );
       }
     } else {
       throw new Error('Geckoprofiler only works in Firefox');

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

@@ -1,16 +1,31 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.javascript');
+/**
+ * Provides functionality to execute JavaScript code in the context of the current page.
+ *
+ * @class
+ * @hideconstructor
+ */
+
 export class JavaScript {
   constructor(browser, pageCompleteCheck) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.pageCompleteCheck = pageCompleteCheck;
   }
 
   /**
-   *  Run JavaScript.
-   * @param {string} js
-   * @returns {Promise} Promise object represents when the JavaScript has been executed by the browser
-   * @throws Will throw an error if the JavsScript can't run
+   * Executes a JavaScript script.
+   *
+   * @async
+   * @param {string} js - The JavaScript code to execute.
+   * @returns {Promise<*>} A promise that resolves with the result of the executed script.
+   * @throws {Error} Throws an error if the JavaScript cannot be executed.
    */
   async run(js) {
     try {
@@ -24,10 +39,12 @@ export class JavaScript {
   }
 
   /**
-   *  Run JavaScript and wait for page complete check to finish.
-   * @param {string} js
-   * @returns {Promise} Promise object represents when the JavaScript has been executed by the browser and the page complete check is done.
-   * @throws Will throw an error if the JavsScript can't run
+   * Executes a JavaScript script and waits for the page complete check to finish.
+   *
+   * @async
+   * @param {string} js - The JavaScript code to execute.
+   * @returns {Promise<*>} A promise that resolves with the result of the executed script and the completion of the page load.
+   * @throws {Error} Throws an error if the JavaScript cannot be executed.
    */
   async runAndWait(js) {
     try {
@@ -41,10 +58,12 @@ export class JavaScript {
   }
 
   /**
-   * Run synchronous privileged JavaScript.
-   * @param {string} js
-   * @returns {Promise} Promise object represents when the JavaScript has been executed by the browser
-   * @throws Will throw an error if the JavsScript can't run
+   * Executes synchronous privileged JavaScript.
+   *
+   * @async
+   * @param {string} js - The privileged JavaScript code to execute.
+   * @returns {Promise<*>} A promise that resolves with the result of the executed privileged script.
+   * @throws {Error} Throws an error if the privileged JavaScript cannot be executed.
    */
   async runPrivileged(js) {
     try {
@@ -61,10 +80,12 @@ export class JavaScript {
   }
 
   /**
-   * Run synchronous privileged JavaScript and wait for page complete check to finish.
-   * @param {string} js
-   * @returns {Promise} Promise object represents when the JavaScript has been executed by the browser and the page complete check is done.
-   * @throws Will throw an error if the JavsScript can't run
+   * Executes synchronous privileged JavaScript and waits for the page complete check to finish.
+   *
+   * @async
+   * @param {string} js - The privileged JavaScript code to execute.
+   * @returns {Promise<*>} A promise that resolves with the result of the executed privileged script and the completion of the page load.
+   * @throws {Error} Throws an error if the privileged JavaScript cannot be executed.
    */
   async runPrivilegedAndWait(js) {
     try {
@@ -78,10 +99,12 @@ export class JavaScript {
   }
 
   /**
-   * Run asynchronous privileged JavaScript.
-   * @param {string} js
-   * @returns {Promise} Promise object represents when the JavaScript has been executed by the browser
-   * @throws Will throw an error if the JavsScript can't run
+   * Executes asynchronous privileged JavaScript.
+   *
+   * @async
+   * @param {string} js - The asynchronous privileged JavaScript code to execute.
+   * @returns {Promise<*>} A promise that resolves with the result of the executed asynchronous privileged script.
+   * @throws {Error} Throws an error if the asynchronous privileged JavaScript cannot be executed.
    */
   async runPrivilegedAsync(js) {
     try {