browsertime 20.0.0 → 21.0.0

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

@@ -0,0 +1,52 @@
+// We disable these because they are needed for code completion
+/* eslint no-unused-vars: "off" */
+import { Actions as SeleniumActions } from 'selenium-webdriver/lib/input.js';
+/**
+ * This class provides an abstraction layer for Selenium's action sequence functionality.
+ * It allows for easy interaction with web elements using different locating strategies
+ * and simulating complex user gestures like mouse movements, key presses, etc.
+ *
+ * @class
+ * @hideconstructor
+ * @see https://www.selenium.dev/documentation/webdriver/actions_api/
+ * @see https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/input_exports_Actions.html
+ */
+export class Actions {
+  constructor(browser) {
+    /**
+     * @private
+     */
+    this.driver = browser.getDriver();
+    /**
+     * @private
+     */
+    this.actions = this.driver.actions({ async: true });
+  }
+
+  /*
+   * Clears the stored actions. You need to manually clear actions, before you start a new action.
+   *
+   * @returns {Promise<void>} A promise that will be resolved when the actions have been
+   *  cleared.
+   */
+  async clear() {
+    return this.driver.actions().clear();
+  }
+
+  /**
+   * Retrieves the current action sequence builder.
+   * The actions builder can be used to chain multiple browser actions.
+   * @returns {SeleniumActions} The current Selenium Actions builder object for chaining browser actions.
+   *  @example
+   * // Example of using the actions builder to perform a drag-and-drop operation:
+   * const elementToDrag = await commands.action.getElementByCss('.draggable');
+   * const dropTarget = await commands.action.getElementByCss('.drop-target');
+   * await commands.action.getAction()
+   *   .dragAndDrop(elementToDrag, dropTarget)
+   *   .perform();
+   *
+   */
+  getActions() {
+    return this.actions;
+  }
+}

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

@@ -2,18 +2,28 @@ import { By } from 'selenium-webdriver';
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.addText');
 
+/**
+ * Provides functionality to add text to elements on a web page using various selectors.
+ * @class
+ * @hideconstructor
+ */
 export class AddText {
   constructor(browser) {
+    /**
+     * @private
+     */
     this.browser = browser;
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} id The id of the element
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its ID.
+   *
+   * @async
+   * @example commands.addText.byId('mytext', 'id');
+   * @param {string} text - The text string to add.
+   * @param {string} id - The ID of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byId(text, id) {
     const driver = this.browser.getDriver();
@@ -30,12 +40,14 @@ export class AddText {
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} xpath The xpath to the element
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its XPath.
+   *
+   * @async
+   * @example commands.addText.byXpath('mytext', 'xpath');
+   * @param {string} text - The text string to add.
+   * @param {string} xpath - The XPath of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byXpath(text, xpath) {
     const driver = this.browser.getDriver();
@@ -52,12 +64,14 @@ export class AddText {
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} selector The CSS selector to the element
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its CSS selector.
+   *
+   * @async
+   * @example commands.addText.bySelector('mytext', 'selector');
+   * @param {string} text - The text string to add.
+   * @param {string} selector - The CSS selector of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async bySelector(text, selector) {
     const driver = this.browser.getDriver();
@@ -74,12 +88,14 @@ export class AddText {
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} className A specific class name
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its class name.
+   *
+   * @async
+   * @example commands.addText.byClassName('mytext', 'className');
+   * @param {string} text - The text string to add.
+   * @param {string} className - The class name of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byClassName(text, className) {
     const driver = this.browser.getDriver();
@@ -96,12 +112,14 @@ export class AddText {
   }
 
   /**
-   * Add text to an element with Selenium sendKeys.
-   * @param {string} text The text string that you want to add
-   * @param {string} name Element whose name attribute has the given value.
-   * @returns {Promise} Promise object represents when the text has been
-   * added to the field
-   * @throws Will throw an error if the element is not found
+   * Adds text to an element identified by its name attribute.
+   *
+   * @async
+   * @example commands.addText.byName('mytext', 'name');
+   * @param {string} text - The text string to add.
+   * @param {string} name - The name attribute of the element.
+   * @returns {Promise<void>} A promise that resolves when the text has been added.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async byName(text, name) {
     const driver = this.browser.getDriver();

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

@@ -1,16 +1,29 @@
 import intel from 'intel';
 import { Android, isAndroidConfigured } from '../../../android/index.js';
 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
+ * @hideconstructor
+ */
 export class AndroidCommand {
   constructor(options) {
+    /**
+     * @private
+     */
     this.options = options;
   }
 
   /**
-   * Run a shell command on your Android phone.
-   * @param {string} command The shell command to run on your phone.
-   * @returns {Promise} Promise object represents the outcome of the command or when the command has finished
-   * @throws Will throw an error Android isn't configured or something goes wrong
+   * Runs a shell command on the connected Android device.
+   * This method requires the Android device to be properly configured.
+   *
+   * @async
+   * @example await commands.android.shell('');
+   * @param {string} command - The shell command to run on the Android device.
+   * @returns {Promise<string>} A promise that resolves with the result of the command or rejects if there's an error.
+   * @throws {Error} Throws an error if Android is not configured or if the command fails.
    */
   async shell(command) {
     if (isAndroidConfigured(this.options)) {
@@ -24,4 +37,30 @@ export class AndroidCommand {
       }
     } else throw new Error('Android is not configured');
   }
+
+  /**
+   * Runs a shell command on the connected Android device as the root user.
+   * This method requires the Android device to be properly configured and that you
+   * rooted the device.
+   *
+   * @async
+   * @example await commands.android.shellAsRoot('');
+   * @param {string} command - The shell command to run on the Android device as root.
+   * @returns {Promise<string>} A promise that resolves with the result of the command or rejects if there's an error.
+   * @throws {Error} Throws an error if Android is not configured or if the command fails.
+   */
+  async shellAsRoot(command) {
+    if (isAndroidConfigured(this.options)) {
+      log.debug('Run %s', command);
+      try {
+        this.a = new Android(this.options);
+        return this.a._runAsRootAndGet(command);
+      } catch (error) {
+        log.error('Could not run shell command as root %s', command, error);
+        throw new Error(
+          `Could not run Android shell commmand as root ${command}`
+        );
+      }
+    } else throw new Error('Android is not configured');
+  }
 }

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

@@ -1,15 +1,43 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.cache');
+/**
+ * Manage the browser cache.
+ * This class provides methods to clear the cache and cookies in different browsers.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Cache {
   constructor(browser, browserName, extensionServer, cdp) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.browserName = browserName;
+    /**
+     * @private
+     */
     this.extensionServer = extensionServer;
+    /**
+     * @private
+     */
     this.cdp = cdp;
   }
 
   /**
-   * Clear the browser cache. Will clear browser cache and cookies.
+   * Clears the browser cache. This includes both cache and cookies.
+   *
+   * For Firefox, it uses the extensionServer setup with specific options.
+   * For Chrome and Edge, it uses the Chrome DevTools Protocol (CDP) commands.
+   * If the browser is not supported, logs an error message.
+   *
+   * @async
+   * @example await commands.cache.clear();
+   * @throws Will throw an error if the browser is not supported.
+   * @returns {Promise<void>} A promise that resolves when the cache and cookies are cleared.
    */
   async clear() {
     if (this.browserName === 'firefox') {
@@ -28,7 +56,16 @@ export class Cache {
   }
 
   /**
-   * Clear the browser cache but keep cookies.
+   * Clears the browser cache while keeping the cookies.
+   *
+   * For Firefox, it uses the extensionServer setup with specific options.
+   * For Chrome and Edge, it uses the Chrome DevTools Protocol (CDP) command to clear the cache.
+   * If the browser is not supported, logs an error message.
+   *
+   * @async
+   * @example await commands.cache.clearKeepCookies();
+   * @throws Will throw an error if the browser is not supported.
+   * @returns {Promise<void>} A promise that resolves when the cache is cleared but cookies are kept.
    */
   async clearKeepCookies() {
     if (this.browserName === 'firefox') {

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

@@ -1,13 +1,34 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.devtoolsprotocol');
 
-// https://chromedevtools.github.io/devtools-protocol/
+/**
+ * Manages interactions with the Chrome DevTools Protocol for Chrome and Edge browsers.
+ * Allows sending commands and setting up event listeners via the protocol.
+ *
+ * @class
+ * @hideconstructor
+ * @see https://chromedevtools.github.io/devtools-protocol/
+ */
 export class ChromeDevelopmentToolsProtocol {
   constructor(engineDelegate, browserName) {
+    /**
+     * @private
+     */
     this.engineDelegate = engineDelegate;
+    /**
+     * @private
+     */
     this.browserName = browserName;
   }
 
+  /**
+   * Sets up an event listener for a specific DevTools Protocol event.
+   *
+   * @async
+   * @param {string} event - The name of the event to listen for.
+   * @param {Function} f - The callback function to execute when the event is triggered.
+   * @throws {Error} Throws an error if the browser is not supported or if setting the listener fails.
+   */
   async on(event, f) {
     if (this.browserName === 'chrome' || this.browserName === 'edge') {
       try {
@@ -29,6 +50,17 @@ export class ChromeDevelopmentToolsProtocol {
     }
   }
 
+  /**
+   * Sends a command to the DevTools Protocol and returns the result.
+   *
+   * @async
+   * @example const domCounters = await commands.cdp.sendAndGet('Memory.getDOMCounters');
+   * @see https://chromedevtools.github.io/devtools-protocol/
+   * @param {string} command - The DevTools Protocol command to send.
+   * @param {Object} arguments_ - The arguments for the command.
+   * @throws {Error} Throws an error if the browser is not supported or if the command fails.
+   * @returns {Promise<Object>} The result of the command execution.
+   */
   async sendAndGet(command, arguments_) {
     if (this.browserName === 'chrome' || this.browserName === 'edge') {
       try {
@@ -51,6 +83,13 @@ export class ChromeDevelopmentToolsProtocol {
     }
   }
 
+  /**
+   * Retrieves the raw client for the DevTools Protocol.
+   * @example const cdpClient = commands.cdp.getRawClient();
+   * @returns {Object} The raw DevTools Protocol client.
+   * @throws {Error} Throws an error if the browser is not supported.
+   * @see https://github.com/cyrus-and/chrome-remote-interface
+   */
   getRawClient() {
     if (this.browserName === 'chrome' || this.browserName === 'edge') {
       return this.engineDelegate.getCDPClient().getRawClient();
@@ -59,6 +98,17 @@ export class ChromeDevelopmentToolsProtocol {
     }
   }
 
+  /**
+   * Sends a command to the DevTools Protocol.
+   *
+   * @async
+   * @example await commands.cdp.send('');
+   * @see https://chromedevtools.github.io/devtools-protocol/
+   * @param {string} command - The DevTools Protocol command to send.
+   * @param {Object} arguments_ - The arguments for the command.
+   * @throws {Error} Throws an error if the browser is not supported or if the command fails.
+   * @returns {Promise<void>} A promise that resolves when the command has been sent.
+   */
   async send(command, arguments_) {
     if (this.browserName === 'chrome' || this.browserName === 'edge') {
       try {

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

@@ -4,14 +4,40 @@ import { getRenderBlocking } from '../../../chrome/webdriver/traceUtilities.js';
 import { parse } from '../../../chrome/traceCategoriesParser.js';
 import { parseCPUTrace } from '../../../chrome/parseCpuTrace.js';
 const log = intel.getLogger('browsertime.command.chrometrace');
+/**
+ * Manages Chrome trace functionality, enabling custom profiling and trace collection in Chrome.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class ChromeTrace {
   constructor(engineDelegate, index, options, result) {
+    /**
+     * @private
+     */
     this.engineDelegate = engineDelegate;
+    /**
+     * @private
+     */
     this.options = options;
+    /**
+     * @private
+     */
     this.result = result;
+    /**
+     * @private
+     */
     this.index = index;
   }
 
+  /**
+   * Starts the Chrome trace collection.
+   *
+   * @async
+   * @example await commands.trace.start();
+   * @returns {Promise<void>} A promise that resolves when tracing is started.
+   * @throws {Error} Throws an error if not running Chrome or if configuration is not set for custom tracing.
+   */
   async start() {
     if (this.options.browser === 'chrome') {
       if (this.options.chrome.timelineRecordingType === 'custom') {
@@ -26,6 +52,14 @@ export class ChromeTrace {
     }
   }
 
+  /**
+   * Stops the Chrome trace collection, processes the collected data, and attaches it to the result object.
+   *
+   * @async
+   * @example await commands.trace.stop();
+   * @returns {Promise<void>} A promise that resolves when tracing is stopped and data is processed.
+   * @throws {Error} Throws an error if not running Chrome or if custom tracing was not started.
+   */
   async stop() {
     if (this.options.browser === 'chrome') {
       if (this.options.chrome.timelineRecordingType === 'custom') {