browsertime 20.0.0 → 21.0.0

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

@@ -27,6 +27,13 @@ function getNewResult() {
   };
 }
 
+/**
+ * A measurement tool for browser-based metrics, handling various aspects
+ * of metric collection including navigation, video recording, and data collection.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Measure {
   constructor(
     browser,
@@ -44,33 +51,104 @@ export class Measure {
     screenshotManager,
     options
   ) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.pageCompleteCheck = pageCompleteCheck;
+    /**
+     * @private
+     */
     this.index = index;
+    /**
+     * @private
+     */
     this.result = result;
+    /**
+     * @private
+     */
     this.engineDelegate = engineDelegate;
+    /**
+     * @private
+     */
     this.options = options;
+    /**
+     * @private
+     */
     this.screenshotManager = screenshotManager;
+    /**
+     * @private
+     */
     this.storageManager = storageManager;
+    /**
+     * @private
+     */
     this.recordVideo = options.visualMetrics || options.video;
+    /**
+     * @private
+     */
     this.extensionServer = extensionServer;
+    /**
+     * @private
+     */
     this.videos = videos;
+    /**
+     * @private
+     */
     this.scriptsByCategory = scriptsByCategory;
+    /**
+     * @private
+     */
     this.asyncScriptsByCategory = asyncScriptsByCategory;
+    /**
+     * @private
+     */
     this.postURLScripts = postURLScripts;
+    /**
+     * @private
+     */
     this.context = context;
+    /**
+     * @private
+     */
     this.numberOfMeasuredPages = 0;
+    /**
+     * @private
+     */
     this.numberOfVisitedPages = 0;
+    /**
+     * @private
+     */
     this.areWeMeasuring = false;
+    /**
+     * @private
+     */
     this.testedURLs = {};
+    /**
+     * @private
+     */
     this.tcpDump = new TCPDump(storageManager.directory, options);
-
+    /**
+     * @private
+     */
     this.ANDROID_DELAY_TIME = get(options, 'orangeAndroidDelayTime', 2000);
+    /**
+     * @private
+     */
     this.IOS_DELAY_TIME = get(options, 'orangeIosDelayTime', 1000);
+    /**
+     * @private
+     */
     this.DESKTOP_DELAY_TIME = get(options, 'orangeDesktopDelayTime', 800);
   }
 
-  // Have a consistent way of starting the video
+  /**
+   * Have a consistent way of starting the video
+   * @private
+   */
   async _startVideo(numberOfMeasuredPages, index) {
     this.video = new Video(this.storageManager, this.options, this.browser);
 
@@ -95,6 +173,10 @@ export class Measure {
     }
   }
 
+  /**
+   * Have a consistent way of starting stopping the video
+   * @private
+   */
   async _stopVideo(url) {
     if (this.recordVideo && !this.options.videoParams.debug) {
       await this.video.stop(url);
@@ -102,6 +184,10 @@ export class Measure {
     }
   }
 
+  /**
+   * Have a consistent way of adding an error
+   * @private
+   */
   _error(message) {
     // If we already are measuring a page, associate the error woth that page
     if (this.areWeMeasuring === true) {
@@ -126,6 +212,10 @@ export class Measure {
     }
   }
 
+  /**
+   * Have a consistent way of adding an failure
+   * @private
+   */
   _failure(message) {
     log.debug('Mark run as failure with message %s', message);
     this.result.markedAsFailure = 1;
@@ -136,6 +226,19 @@ export class Measure {
     }
   }
 
+  /**
+   * Navigates to a specified URL and handles additional setup for the first page visit.
+   *
+   * This function is responsible for setting up the browser with necessary configurations and
+   * navigating to the URL. It also waits for the page
+   * to load completely based on configured page completion check.
+   *
+   * @async
+   * @private
+   * @param {string} url - The URL to navigate to.
+   * @throws {Error} Throws an error if navigation or setup fails.
+   * @returns {Promise<void>} A promise that resolves when the navigation and setup are complete.
+   */
   async _navigate(url) {
     log.info('Navigating to url %s iteration %s', url, this.index);
     if (this.numberOfVisitedPages === 0) {
@@ -162,12 +265,24 @@ export class Measure {
   }
 
   /**
-   *  Start collecting metrics for a URL. If you supply a URL to this method, the browser will navigate to that URL.
-   *  If you do not use an URL (start()) everything is prepared for a new page to measure except the browser do not
-   *  navigate to a new URL. You can also add an alias for the URL.
-   * @param {string} urlOrAlias
-   * @param {string} optionalAlias
-   * @returns {Promise} Promise object represents when the URL has been navigated and finished loading according to the pageCompleteCheck or when everything is setup for measuring a new URL (if no URL is supplied).
+   * Starts the measurement process for a given URL or an alias.
+   *
+   * It supports starting measurements by either directly providing a URL or using an alias.
+   * If a URL is provided, it navigates to that URL and performs the measurement.
+   * If an alias is provided, or no URL is available, it sets up the environment for a user-driven navigation.
+   *
+   * @async
+   * @example
+   * await commands.measure.start('https://www.example.org');
+   * // Or start the measurement and click on a link
+   * await commands.measure.start();
+   * await commands.click.byLinkTextAndWait('Documentation');
+   * // Remember to stop the measurements if you do not provide a URL
+   * await commands.measure.stop();
+   * @param {string} urlOrAlias - The URL to navigate to, or an alias representing the test.
+   * @param {string} [optionalAlias] - An optional alias that can be used if the first parameter is a URL.
+   * @throws {Error} Throws an error if navigation fails or if there are issues in the setup process.
+   * @returns {Promise<void>} A promise that resolves when the start process is complete, or rejects if there are errors.
    */
   async start(urlOrAlias, optionalAlias) {
     let url, alias;
@@ -258,8 +373,14 @@ export class Measure {
   }
 
   /**
-   * Stop measuring and collect all the metrics.
-   * @returns {Promise} Promise object represents all the metrics has been collected.
+   * Stops the measurement process, collects metrics, and handles any post-measurement tasks.
+   * It finalizes the URL being tested, manages any URL-specific metadata, stops any ongoing video recordings,
+   * and initiates the data collection process.
+   *
+   * @async
+   * @param {string} testedStartUrl - The URL that was initially tested. If not provided, it will be obtained from the browser.
+   * @throws {Error} Throws an error if there are issues in stopping the measurement or collecting data.
+   * @returns {Promise} A promise that resolves with the collected metrics data.
    */
   async stop(testedStartUrl) {
     log.debug('Stop measuring');
@@ -326,9 +447,12 @@ export class Measure {
   }
 
   /**
-   * Add your own metric.
-   * @param {string} name
-   * @param {*} value
+   * Adds a custom metric to the current measurement result.
+   * This method should be called after a measurement has started and before it has stopped.
+   *
+   * @param {string} name - The name of the metric.
+   * @param {*} value - The value of the metric.
+   * @throws {Error} Throws an error if called before a measurement cycle has started.
    */
   add(name, value) {
     if (this.result[this.numberOfMeasuredPages - 1]) {
@@ -341,8 +465,12 @@ export class Measure {
   }
 
   /**
-   * Add your own metrics. You can add an object witch multiple keys and they will all be collected.
-   * @param {*} object
+   * Adds multiple custom metrics to the current measurement result.
+   * This method accepts an object containing multiple key-value pairs representing different metrics.
+   * Similar to `add`, it should be used within an active measurement cycle.
+   *
+   * @param {Object} object - An object containing key-value pairs of metrics to add.
+   * @throws {Error} Throws an error if called before a measurement cycle has started.
    */
   addObject(object) {
     if (this.result[this.numberOfMeasuredPages - 1]) {
@@ -353,6 +481,10 @@ export class Measure {
       );
   }
 
+  /**
+   *
+   * @private
+   */
   async collect(url) {
     if (this.options.tcpdump) {
       await this.tcpDump.stop();

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

@@ -1,9 +1,26 @@
+/**
+ * Add meta data to your user journey.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Meta {
   constructor() {}
 
+  /**
+   * Sets the description for the user journey.
+   * @example commands.meta.setDescription('My test');
+   * @param {string} text - The text to set as the description.
+   */
   setDescription(text) {
     this.description = text;
   }
+
+  /**
+   * Sets the title for the user journey.
+   * @example commands.meta.setTitle('Test title');
+   * @param {string} text - The text to set as the title.
+   */
   setTitle(text) {
     this.title = text;
   }

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

@@ -1,17 +1,32 @@
 import intel from 'intel';
 import { By, Origin } from 'selenium-webdriver';
 const log = intel.getLogger('browsertime.command.mouse');
+
+/**
+ * Provides functionality to click and hold elements on a web page using different strategies.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class ClickAndHold {
   constructor(browser) {
+    /**
+     * @private
+     */
     this.driver = browser.getDriver();
+    /**
+     * @private
+     */
     this.actions = this.driver.actions({ async: true });
   }
 
   /**
-   * Click and hold an element that matches a XPath selector.
-   * @param {string} xpath
-   * @returns {Promise} Promise object represents when mouse is pressed.
-   * @throws Will throw an error if the element is not found.
+   * Clicks and holds on an element that matches a given XPath selector.
+   *
+   * @async
+   * @param {string} xpath - The XPath selector of the element to interact with.
+   * @returns {Promise<void>} A promise that resolves when the action is performed.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byXpath(xpath) {
     try {
@@ -27,10 +42,12 @@ export class ClickAndHold {
   }
 
   /**
-   * Click and hold an element that matches a CSS selector.
-   * @param {string} selector
-   * @returns {Promise} Promise object represents when mouse is pressed.
-   * @throws Will throw an error if the element is not found.
+   * Clicks and holds on an element that matches a given CSS selector.
+   *
+   * @async
+   * @param {string} selector - The CSS selector of the element to interact with.
+   * @returns {Promise<void>} A promise that resolves when the action is performed.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async bySelector(selector) {
     try {
@@ -49,9 +66,11 @@ export class ClickAndHold {
   }
 
   /**
-   * Click and hold an element at the cursor's position.
-   * @returns {Promise} Promise object represents when mouse is pressed.
-   * @throws Will throw an error if action cannot be performed.
+   * Clicks and holds at the current cursor position.
+   *
+   * @async
+   * @returns {Promise<void>} A promise that resolves when the action is performed.
+   * @throws {Error} Throws an error if the action cannot be performed.
    */
   async atCursor() {
     try {
@@ -64,11 +83,13 @@ export class ClickAndHold {
   }
 
   /**
-   * Click and hold an element at the given coordinates.
-   * @param {integer} xPos
-   * @param {integer} yPos
-   * @returns {Promise} Promise object represents when mouse is pressed.
-   * @throws Will throw an error if action cannot be performed.
+   * Clicks and holds at the specified screen coordinates.
+   *
+   * @async
+   * @param {number} xPos - The x-coordinate on the screen.
+   * @param {number} yPos - The y-coordinate on the screen.
+   * @returns {Promise<void>} A promise that resolves when the action is performed.
+   * @throws {Error} Throws an error if the action cannot be performed.
    */
   async atPosition(xPos, yPos) {
     try {
@@ -86,10 +107,12 @@ export class ClickAndHold {
   }
 
   /**
-   * Release mouse on element that matches the specified Xpath.
-   * @param {string} xpath
-   * @returns {Promise} Promise object represents when mouse is released.
-   * @throws Will throw an error if action cannot be performed.
+   * Releases the mouse button on an element matching the specified XPath.
+   *
+   * @async
+   * @param {string} xpath - The XPath selector of the element to release the mouse on.
+   * @returns {Promise<void>} A promise that resolves when the action is performed.
+   * @throws {Error} Throws an error if the action cannot be performed.
    */
   async releaseAtXpath(xpath) {
     try {
@@ -103,10 +126,12 @@ export class ClickAndHold {
   }
 
   /**
-   * Release mouse on element that matches the specified CSS selector.
-   * @param {string} selector
-   * @returns {Promise} Promise object represents when mouse is released.
-   * @throws Will throw an error if action cannot be performed.
+   * Releases the mouse button on an element matching the specified CSS selector.
+   *
+   * @async
+   * @param {string} selector - The CSS selector of the element to release the mouse on.
+   * @returns {Promise<void>} A promise that resolves when the action is performed.
+   * @throws {Error} Throws an error if the action cannot be performed.
    */
   async releaseAtSelector(selector) {
     try {
@@ -120,11 +145,13 @@ export class ClickAndHold {
   }
 
   /**
-   * Release mouse at specified coordinates.
-   * @param {integer} xPos
-   * @param {integer} yPos
-   * @returns {Promise} Promise object represents when mouse is released.
-   * @throws Will throw an error if action cannot be performed.
+   * Releases the mouse button at the specified screen coordinates.
+   *
+   * @async
+   * @param {number} xPos - The x-coordinate on the screen.
+   * @param {number} yPos - The y-coordinate on the screen.
+   * @returns {Promise<void>} A promise that resolves when the action is performed.
+   * @throws {Error} Throws an error if the action cannot be performed.
    */
   async releaseAtPosition(xPos, yPos) {
     try {

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

@@ -1,17 +1,32 @@
 import intel from 'intel';
 import { By } from 'selenium-webdriver';
 const log = intel.getLogger('browsertime.command.mouse');
+
+/**
+ * Provides functionality to perform a context click (right-click) on elements in a web page.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class ContextClick {
   constructor(browser) {
+    /**
+     * @private
+     */
     this.driver = browser.getDriver();
+    /**
+     * @private
+     */
     this.actions = this.driver.actions({ async: true });
   }
 
   /**
-   * Perform ContextClick on an element that matches a XPath selector.
-   * @param {string} xpath
-   * @returns {Promise} Promise object represents when context click occurs.
-   * @throws Will throw an error if the element is not found
+   * Performs a context click (right-click) on an element that matches a given XPath selector.
+   *
+   * @async
+   * @param {string} xpath - The XPath selector of the element to context click.
+   * @returns {Promise<void>} A promise that resolves when the context click action is performed.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byXpath(xpath) {
     try {
@@ -25,10 +40,12 @@ export class ContextClick {
   }
 
   /**
-   * Perform ContextClick on an element that matches a CSS selector.
-   * @param {string} css selector
-   * @returns {Promise} Promise object represents when context click occurs.
-   * @throws Will throw an error if the element is not found
+   * Performs a context click (right-click) on an element that matches a given CSS selector.
+   *
+   * @async
+   * @param {string} selector - The CSS selector of the element to context click.
+   * @returns {Promise<void>} A promise that resolves when the context click action is performed.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async bySelector(selector) {
     try {
@@ -44,9 +61,11 @@ export class ContextClick {
   }
 
   /**
-   * Perform ContextClick at the cursor's position.
-   * @returns {Promise} Promise object represents when context click occurs.
-   * @throws Will throw an error if context click cannot be performed.
+   * Performs a context click (right-click) at the current cursor position.
+   *
+   * @async
+   * @returns {Promise<void>} A promise that resolves when the context click action is performed.
+   * @throws {Error} Throws an error if the context click action cannot be performed.
    */
   async atCursor() {
     try {

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

@@ -1,18 +1,36 @@
 import intel from 'intel';
 import { By } from 'selenium-webdriver';
 const log = intel.getLogger('browsertime.command.mouse');
+/**
+ * Provides functionality to perform a double-click action on elements in a web page.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class DoubleClick {
   constructor(browser, pageCompleteCheck) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.actions = this.browser.getDriver().actions({ async: true });
+    /**
+     * @private
+     */
     this.pageCompleteCheck = pageCompleteCheck;
   }
 
   /**
-   * Perform mouse double click on an element matches a XPath selector.
-   * @param {string} xpath
-   * @returns {Promise} Promise object represents when the element has been double clicked.
-   * @throws Will throw an error if the element is not found.
+   * Performs a mouse double-click on an element matching a given XPath selector.
+   *
+   * @async
+   * @param {string} xpath - The XPath selector of the element to double-click.
+   * @param {Object} [options] - Additional options for the double-click action.
+   * @returns {Promise<void>} A promise that resolves when the double-click action is performed.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byXpath(xpath, options) {
     try {
@@ -31,10 +49,13 @@ export class DoubleClick {
   }
 
   /**
-   * Perform mouse double click on an element matches a CSS selector.
-   * @param {string} selector
-   * @returns {Promise} Promise object represents when the element has been double clicked.
-   * @throws Will throw an error if the element is not found.
+   * Performs a mouse double-click on an element matching a given CSS selector.
+   *
+   * @async
+   * @param {string} selector - The CSS selector of the element to double-click.
+   * @param {Object} [options] - Additional options for the double-click action.
+   * @returns {Promise<void>} A promise that resolves when the double-click action is performed.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async bySelector(selector, options) {
     try {
@@ -55,9 +76,12 @@ export class DoubleClick {
   }
 
   /**
-   * Perform mouse double click at the cursor's position.
-   * @returns {Promise} Promise object represents when double click occurs.
-   * @throws Will throw an error if double click cannot be performed.
+   * Performs a mouse double-click at the current cursor position.
+   *
+   * @async
+   * @param {Object} [options] - Additional options for the double-click action.
+   * @returns {Promise<void>} A promise that resolves when the double-click occurs.
+   * @throws {Error} Throws an error if the double-click action cannot be performed.
    */
   async atCursor(options) {
     try {

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

@@ -1,17 +1,31 @@
 import intel from 'intel';
 import { By, Origin } from 'selenium-webdriver';
 const log = intel.getLogger('browsertime.command.mouse');
+/**
+ * Provides functionality to move the mouse cursor to elements or specific positions on a web page.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class MouseMove {
   constructor(browser) {
+    /**
+     * @private
+     */
     this.driver = browser.getDriver();
+    /**
+     * @private
+     */
     this.actions = this.driver.actions({ async: true });
   }
 
   /**
-   * Move mouse to an element that matches a XPath selector.
-   * @param {string} xpath
-   * @returns {Promise} Promise object represents when the mouse has moved
-   * @throws Will throw an error if the element is not found
+   * Moves the mouse cursor to an element that matches a given XPath selector.
+   *
+   * @async
+   * @param {string} xpath - The XPath selector of the element to move to.
+   * @returns {Promise<void>} A promise that resolves when the mouse has moved to the element.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byXpath(xpath) {
     try {
@@ -25,10 +39,12 @@ export class MouseMove {
   }
 
   /**
-   * Move mouse to an element that matches a CSS selector.
-   * @param {string} selector
-   * @returns {Promise} Promise object represents when the mouse has moved
-   * @throws Will throw an error if the element is not found
+   * Moves the mouse cursor to an element that matches a given CSS selector.
+   *
+   * @async
+   * @param {string} selector - The CSS selector of the element to move to.
+   * @returns {Promise<void>} A promise that resolves when the mouse has moved to the element.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async bySelector(selector) {
     try {
@@ -42,10 +58,13 @@ export class MouseMove {
   }
 
   /**
-   * Move mouse to a position
-   * @param {number} xPos, {number} yPos
-   * @returns {Promise} Promise object represents when the mouse has moved
-   * @throws Will throw an error if the element is not found
+   * Moves the mouse cursor to a specific position on the screen.
+   *
+   * @async
+   * @param {number} xPos - The x-coordinate on the screen to move to.
+   * @param {number} yPos - The y-coordinate on the screen to move to.
+   * @returns {Promise<void>} A promise that resolves when the mouse has moved to the specified position.
+   * @throws {Error} Throws an error if the action cannot be performed.
    */
   async toPosition(xPos, yPos) {
     try {
@@ -58,10 +77,13 @@ export class MouseMove {
   }
 
   /**
-   * Move mouse by an offset
-   * @param {number} xOffset, {number} yOffset
-   * @returns {Promise} Promise object represents when the mouse has moved
-   * @throws Will throw an error if the element is not found
+   * Moves the mouse cursor by an offset from its current position.
+   *
+   * @async
+   * @param {number} xOffset - The x offset to move by.
+   * @param {number} yOffset - The y offset to move by.
+   * @returns {Promise<void>} A promise that resolves when the mouse has moved by the specified offset.
+   * @throws {Error} Throws an error if the action cannot be performed.
    */
   async byOffset(xOffset, yOffset) {
     try {