browsertime 20.0.0 → 21.0.0

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

@@ -1,18 +1,28 @@
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.set');
 
+/**
+ * Provides functionality to set properties like innerHTML, innerText, and value on elements in a web page.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Set {
   constructor(browser) {
+    /**
+     * @private
+     */
     this.browser = browser;
   }
 
   /**
-   * Set innerHtml to an element using a specific CSS selector.
-   * @param {string} html The html string that you want to set
-   * @param {string} selector The selector of the element
-   * @returns {Promise} Promise object represents when the html has been
-   * set to the element
-   * @throws Will throw an error if the element is not found
+   * Sets the innerHTML of an element using a CSS selector.
+   *
+   * @async
+   * @param {string} html - The HTML string to set as innerHTML.
+   * @param {string} selector - The CSS selector of the element.
+   * @returns {Promise<void>} A promise that resolves when the innerHTML is set.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async innerHtml(html, selector) {
     try {
@@ -28,12 +38,13 @@ export class Set {
   }
 
   /**
-   * Set innerHtml to an element using a id
-   * @param {string} html The html string that you want to set
-   * @param {string} id The id of the element
-   * @returns {Promise} Promise object represents when the html has been
-   * set to the element
-   * @throws Will throw an error if the element is not found
+   * Sets the innerHTML of an element using its ID.
+   *
+   * @async
+   * @param {string} html - The HTML string to set as innerHTML.
+   * @param {string} id - The ID of the element.
+   * @returns {Promise<void>} A promise that resolves when the innerHTML is set.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async innerHtmlById(html, id) {
     try {
@@ -47,12 +58,13 @@ export class Set {
   }
 
   /**
-   * Set innerText to an element using a specific CSS selector.
-   * @param {string} html The html string that you want to set
-   * @param {string} selector The selector of the element
-   * @returns {Promise} Promise object represents when the text has been
-   * set to the element
-   * @throws Will throw an error if the element is not found
+   * Sets the innerText of an element using a CSS selector.
+   *
+   * @async
+   * @param {string} text - The text to set as innerText.
+   * @param {string} selector - The CSS selector of the element.
+   * @returns {Promise<void>} A promise that resolves when the innerText is set.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async innerText(text, selector) {
     try {
@@ -68,12 +80,13 @@ export class Set {
   }
 
   /**
-   * Set innerText to an element using a id.
-   * @param {string} html The html string that you want to set
-   * @param {string} id The id of the element
-   * @returns {Promise} Promise object represents when the text has been
-   * set to the element
-   * @throws Will throw an error if the element is not found
+   * Sets the innerText of an element using its ID.
+   *
+   * @async
+   * @param {string} text - The text to set as innerText.
+   * @param {string} id - The ID of the element.
+   * @returns {Promise<void>} A promise that resolves when the innerText is set.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async innerTextById(text, id) {
     try {
@@ -87,12 +100,13 @@ export class Set {
   }
 
   /**
-   * Set value to an element using a specific CSS selector.
-   * @param {string} value The value that you want to set
-   * @param {string} selector The selector of the element
-   * @returns {Promise} Promise object represents when the value has been
-   * added to element
-   * @throws Will throw an error if the element is not found
+   * Sets the value of an element using a CSS selector.
+   *
+   * @async
+   * @param {string} value - The value to set on the element.
+   * @param {string} selector - The CSS selector of the element.
+   * @returns {Promise<void>} A promise that resolves when the value is set.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async value(value, selector) {
     try {
@@ -106,12 +120,13 @@ export class Set {
   }
 
   /**
-   * Set value to an element using a id.
-   * @param {string} value The value that you want to set
-   * @param {string} selector The selector of the element
-   * @returns {Promise} Promise object represents when the value has been
-   * added to element
-   * @throws Will throw an error if the element is not found
+   * Sets the value of an element using its ID.
+   *
+   * @async
+   * @param {string} value - The value to set on the element.
+   * @param {string} id - The ID of the element.
+   * @returns {Promise<void>} A promise that resolves when the value is set.
+   * @throws {Error} Throws an error if the element is not found.
    */
   async valueById(value, id) {
     try {

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

@@ -1,25 +1,40 @@
 import { performance } from 'node:perf_hooks';
 import intel from 'intel';
 const log = intel.getLogger('browsertime.command.stopwatch');
+
+/**
+ * A stopwatch utility for measuring time intervals.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class StopWatch {
   constructor(name, measure) {
+    /**
+     * @private
+     */
     this.name = name;
+    /**
+     * @private
+     */
     this.measure = measure;
+    /**
+     * @private
+     */
     this.start = performance.now();
   }
 
   /**
-   * Start the the stop watch
+   * Starts the stopwatch.
    */
   start() {
     this.start = performance.now();
   }
 
   /**
-   * Stop the watch and automatically add the time to the
-   * last measured page. If no page has been measured you will get
-   * an error in your log.
-   * @returns the measured time
+   * Stops the stopwatch and automatically adds the measured time to the
+   * last measured page. Logs an error if no page has been measured.
+   * @returns {number} The measured time in milliseconds.
    */
   stopAndAdd() {
     this.stop = performance.now();
@@ -29,8 +44,8 @@ export class StopWatch {
   }
 
   /**
-   * Stop the watch
-   * @returns the measured time
+   * Stops the stopwatch.
+   * @returns {number} The measured time in milliseconds.
    */
   stop() {
     this.stop = performance.now();
@@ -39,19 +54,25 @@ export class StopWatch {
   }
 
   /**
-   * Get the name of the watch.
-   * @returns The name of the watch
+   * Gets the name of the stopwatch.
+   * @returns {string} The name of the stopwatch.
    */
   getName() {
     return this.name;
   }
 }
 
+/**
+ * @private
+ */
 export class Watch {
   constructor(measure) {
     this.measure = measure;
   }
 
+  /**
+   * @private
+   */
   get(name) {
     return new StopWatch(name, this.measure);
   }

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

@@ -2,16 +2,34 @@ import intel from 'intel';
 import { By } from 'selenium-webdriver';
 const log = intel.getLogger('browsertime.command.switch');
 
+/**
+ * Provides functionality to switch between frames, windows, and tabs in the browser.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Switch {
   constructor(browser, pageCompleteCheck, navigate) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.pageCompleteCheck = pageCompleteCheck;
+    /**
+     * @private
+     */
     this.navigate = navigate;
   }
 
   /**
-   * Switch to frame by id
-   * @param {*} id
+   * Switches to a frame identified by its ID.
+   *
+   * @async
+   * @param {string|number} id - The ID of the frame.
+   * @throws {Error} Throws an error if switching to the frame fails.
    */
   async toFrame(id) {
     const driver = this.browser.getDriver();
@@ -25,8 +43,11 @@ export class Switch {
   }
 
   /**
-   * Switch to frame by xpath
-   * @param {*} xpath
+   * Switches to a frame identified by an XPath.
+   *
+   * @async
+   * @param {string} xpath - The XPath of the frame element.
+   * @throws {Error} Throws an error if the frame is not found or switching fails.
    */
   async toFrameByXpath(xpath) {
     const driver = this.browser.getDriver();
@@ -46,8 +67,11 @@ export class Switch {
   }
 
   /**
-   * Switch to frame by xpath
-   * @param {*} xpath
+   * Switches to a frame identified by a CSS selector.
+   *
+   * @async
+   * @param {string} selector - The CSS selector of the frame element.
+   * @throws {Error} Throws an error if the frame is not found or switching fails.
    */
   async toFrameBySelector(selector) {
     const driver = this.browser.getDriver();
@@ -67,8 +91,11 @@ export class Switch {
   }
 
   /**
-   * Switch to a window by name
-   * @param {*} name
+   * Switches to a window identified by its name.
+   *
+   * @async
+   * @param {string} name - The name of the window.
+   * @throws {Error} Throws an error if switching to the window fails.
    */
   async toWindow(name) {
     const driver = this.browser.getDriver();
@@ -82,7 +109,10 @@ export class Switch {
   }
 
   /**
-   * Switch to parent frame
+   * Switches to the parent frame of the current frame.
+   *
+   * @async
+   * @throws {Error} Throws an error if switching to the parent frame fails.
    */
   async toParentFrame() {
     const driver = this.browser.getDriver();
@@ -96,7 +126,11 @@ export class Switch {
   }
 
   /**
-   * Create a new tab and switch to it. Optionally, navigate to a given url.
+   * Opens a new tab and optionally navigates to a URL.
+   *
+   * @async
+   * @param {string} [url] - Optional URL to navigate to in the new tab.
+   * @throws {Error} Throws an error if opening a new tab fails.
    */
   async toNewTab(url) {
     try {
@@ -115,7 +149,11 @@ export class Switch {
   }
 
   /**
-   * Create a new window and switch to it. Optionally, navigate to a given url.
+   * Opens a new window and optionally navigates to a URL.
+   *
+   * @async
+   * @param {string} [url] - Optional URL to navigate to in the new window.
+   * @throws {Error} Throws an error if opening a new window fails.
    */
   async toNewWindow(url) {
     try {

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

@@ -3,18 +3,32 @@ import intel from 'intel';
 const log = intel.getLogger('browsertime.command.wait');
 const delay = ms => new Promise(res => setTimeout(res, ms));
 
+/**
+ * Provides functionality to wait for different conditions in the browser.
+ *
+ * @class
+ * @hideconstructor
+ */
 export class Wait {
   constructor(browser, pageCompleteCheck) {
+    /**
+     * @private
+     */
     this.browser = browser;
+    /**
+     * @private
+     */
     this.pageCompleteCheck = pageCompleteCheck;
   }
 
   /**
-   * Wait for an element with id to appear for maxTime.
-   * @param {string} id The id to wait for
-   * @param {number} maxTime Max time to wait in ms
-   * @returns {Promise} Promise object represents when the element is found or the time times out
-   * @throws Will throw an error if the element is not found
+   * Waits for an element with a specific ID to appear within a maximum time.
+   *
+   * @async
+   * @param {string} id - The ID of the element to wait for.
+   * @param {number} maxTime - Maximum time to wait in milliseconds.
+   * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
+   * @throws {Error} Throws an error if the element is not found within the specified time.
    */
   async byId(id, maxTime) {
     const driver = this.browser.getDriver();
@@ -33,11 +47,13 @@ export class Wait {
   }
 
   /**
-   * Wait for an element with xpath to appear for maxTime.
-   * @param {string} xpath The xpath to wait for
-   * @param {number} maxTime Max time to wait in ms
-   * @returns {Promise} Promise object represents when the element is found or the time times out
-   * @throws Will throw an error if the element is not found
+   * Waits for an element located by XPath to appear within a maximum time.
+   *
+   * @async
+   * @param {string} xpath - The XPath of the element to wait for.
+   * @param {number} maxTime - Maximum time to wait in milliseconds.
+   * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
+   * @throws {Error} Throws an error if the element is not found within the specified time.
    */
   async byXpath(xpath, maxTime) {
     const driver = this.browser.getDriver();
@@ -58,11 +74,13 @@ export class Wait {
   }
 
   /**
-   * Wait for an element that you find by a selector to appear for maxTime.
-   * @param {string} selector The selector to find the element to wait for
-   * @param {number} maxTime Max time to wait in ms
-   * @returns {Promise} Promise object represents when the element is found or the time times out
-   * @throws Will throw an error if the element is not found
+   * Waits for an element located by a CSS selector to appear within a maximum time.
+   *
+   * @async
+   * @param {string} selector - The CSS selector of the element to wait for.
+   * @param {number} maxTime - Maximum time to wait in milliseconds.
+   * @returns {Promise<void>} A promise that resolves when the element is found or the time times out.
+   * @throws {Error} Throws an error if the element is not found within the specified time.
    */
   async bySelector(selector, maxTime) {
     const driver = this.browser.getDriver();
@@ -87,28 +105,35 @@ export class Wait {
   }
 
   /**
-   * Wait for x ms.
-   * @param {number} ms The tine in ms to wait.
-   * @returns {Promise} Promise object represents when the time has timed out.
+   * Waits for a specified amount of time.
+   *
+   * @async
+   * @example async commands.wait.byTime(1000);
+   * @param {number} ms - The time in milliseconds to wait.
+   * @returns {Promise<void>} A promise that resolves when the specified time has elapsed.
    */
   async byTime(ms) {
     return delay(ms);
   }
 
   /**
-   * Wait for the page to finish loading.
-   * @returns {Promise} Promise object represents when the pageCompleteCheck has finished.
+   * Waits for the page to finish loading.
+   * @async
+   * @example async commands.wait.byPageToComplete();
+   * @returns {Promise<void>} A promise that resolves when the page complete check has finished.
    */
   async byPageToComplete() {
     return this.browser.extraWait(this.pageCompleteCheck);
   }
 
   /**
-   * Wait for an condition that will eventually return a truthy-value for maxTime.
-   * @param {string} jsExpression The js code condition to wait for
-   * @param {number} maxTime Max time to wait in ms
-   * @returns {Promise} Promise object represents when the expression becomes truthy or the time times out
-   * @throws Will throw an error if the condition returned false
+   * Waits for a JavaScript condition to return a truthy value within a maximum time.
+   *
+   * @async
+   * @param {string} jsExpression - The JavaScript expression to evaluate.
+   * @param {number} maxTime - Maximum time to wait in milliseconds.
+   * @returns {Promise<void>} A promise that resolves when the condition becomes truthy or the time times out.
+   * @throws {Error} Throws an error if the condition is not met within the specified time.
    */
   async byCondition(jsExpression, maxTime) {
     const driver = this.browser.getDriver();