browsertime 26.3.2 → 27.0.0

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

@@ -0,0 +1,85 @@
+import { getLogger } from '@sitespeed.io/log';
+const log = getLogger('browsertime.command.cookie');
+
+/**
+ * Provides functionality to manage browser cookies.
+ *
+ * @class
+ * @hideconstructor
+ */
+export class Cookie {
+  constructor(browser) {
+    /**
+     * @private
+     */
+    this.driver = browser.getDriver();
+  }
+
+  /**
+   * Gets all cookies for the current page.
+   *
+   * @async
+   * @returns {Promise<Array>} An array of cookie objects.
+   */
+  async getAll() {
+    return this.driver.manage().getCookies();
+  }
+
+  /**
+   * Gets a specific cookie by name.
+   *
+   * @async
+   * @param {string} name - The name of the cookie.
+   * @returns {Promise<Object|undefined>} The cookie object, or undefined if not found.
+   */
+  async get(name) {
+    try {
+      return await this.driver.manage().getCookie(name);
+    } catch {
+      // Cookie not found
+    }
+  }
+
+  /**
+   * Sets a cookie.
+   *
+   * @async
+   * @param {string} name - The name of the cookie.
+   * @param {string} value - The value of the cookie.
+   * @param {Object} [options] - Optional cookie properties.
+   * @param {string} [options.domain] - The domain the cookie is visible to.
+   * @param {string} [options.path] - The cookie path.
+   * @param {boolean} [options.secure] - Whether the cookie is secure.
+   * @param {boolean} [options.httpOnly] - Whether the cookie is HTTP only.
+   * @param {Date} [options.expiry] - When the cookie expires.
+   * @returns {Promise<void>}
+   */
+  async set(name, value, options = {}) {
+    const cookie = { name, value, ...options };
+    log.debug('Setting cookie %s', name);
+    return this.driver.manage().addCookie(cookie);
+  }
+
+  /**
+   * Deletes a specific cookie by name.
+   *
+   * @async
+   * @param {string} name - The name of the cookie to delete.
+   * @returns {Promise<void>}
+   */
+  async delete(name) {
+    log.debug('Deleting cookie %s', name);
+    return this.driver.manage().deleteCookie(name);
+  }
+
+  /**
+   * Deletes all cookies for the current page.
+   *
+   * @async
+   * @returns {Promise<void>}
+   */
+  async deleteAll() {
+    log.debug('Deleting all cookies');
+    return this.driver.manage().deleteAllCookies();
+  }
+}

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

@@ -1,17 +1,21 @@
 // We disable these because they are needed for code completion
 /* eslint no-unused-vars: "off" */
-import { By, WebElement } from 'selenium-webdriver';
+import webdriver, { By, WebElement } from 'selenium-webdriver';
 /**
  * This class provides a way to get hokld of Seleniums WebElements.
  * @class
  * @hideconstructor
  */
 export class Element {
-  constructor(browser) {
+  constructor(browser, options) {
     /**
      * @private
      */
     this.driver = browser.getDriver();
+    /**
+     * @private
+     */
+    this.options = options;
   }
 
   /**
@@ -63,4 +67,35 @@ export class Element {
   async getByName(name) {
     return this.driver.findElement(By.name(name));
   }
+
+  /**
+   * Finds an element using a CSS selector, with optional waiting and visibility check.
+   *
+   * @param {string} selector - The CSS selector of the element.
+   * @param {Object} [options] - Options for finding the element.
+   * @param {number} [options.timeout] - Maximum time in milliseconds to wait for the element. Defaults to the configured --timeouts.elementWait value.
+   * @param {boolean} [options.visible=false] - If true, waits for the element to be visible, not just present.
+   * @returns {Promise<WebElement>} A promise that resolves to the WebElement found.
+   * @throws {Error} Throws an error if the element is not found within the timeout.
+   */
+  async find(selector, options = {}) {
+    const timeout = options.timeout ?? this.options?.timeouts?.elementWait ?? 0;
+    const visible = options.visible ?? false;
+    const locator = By.css(selector);
+
+    if (timeout > 0) {
+      const element = await this.driver.wait(
+        webdriver.until.elementLocated(locator),
+        timeout
+      );
+      if (visible) {
+        await this.driver.wait(
+          webdriver.until.elementIsVisible(element),
+          timeout
+        );
+      }
+      return element;
+    }
+    return this.driver.findElement(locator);
+  }
 }

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

@@ -1,4 +1,5 @@
 import { getLogger } from '@sitespeed.io/log';
+import { executeCommand } from './commandHelper.js';
 const log = getLogger('browsertime.command.javascript');
 /**
  * Provides functionality to execute JavaScript code in the context of the current page.
@@ -19,6 +20,14 @@ export class JavaScript {
     this.pageCompleteCheck = pageCompleteCheck;
   }
 
+  /**
+   * @private
+   */
+  async _andWait(baseMethod, ...args) {
+    await baseMethod.apply(this, args);
+    return this.browser.extraWait(this.pageCompleteCheck);
+  }
+
   /**
    * Executes a JavaScript script.
    *
@@ -28,14 +37,9 @@ export class JavaScript {
    * @throws {Error} Throws an error if the JavaScript cannot be executed.
    */
   async run(js) {
-    try {
-      const value = await this.browser.runScript(js, 'CUSTOM');
-      return value;
-    } catch (error) {
-      log.error('Could not run JavaScript %s ', js);
-      log.verbose(error);
-      throw new Error(`Could not run JavaScript ${js}`);
-    }
+    return executeCommand(log, 'Could not run JavaScript %s', js, () =>
+      this.browser.runScript(js, 'CUSTOM')
+    );
   }
 
   /**
@@ -47,14 +51,7 @@ export class JavaScript {
    * @throws {Error} Throws an error if the JavaScript cannot be executed.
    */
   async runAndWait(js) {
-    try {
-      await this.browser.runScript(js, 'CUSTOM');
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not run JavaScript %s ', js);
-      log.verbose(error);
-      throw new Error(`Could not run JavaScript ${js}`);
-    }
+    return this._andWait(this.run, js);
   }
 
   /**
@@ -88,14 +85,7 @@ export class JavaScript {
    * @throws {Error} Throws an error if the privileged JavaScript cannot be executed.
    */
   async runPrivilegedAndWait(js) {
-    try {
-      await this.browser.runPrivilegedScript(js, 'CUSTOM PRIVILEGED');
-      return this.browser.extraWait(this.pageCompleteCheck);
-    } catch (error) {
-      log.error('Could not run privileged JavaScript %s ', js);
-      log.verbose(error);
-      throw error;
-    }
+    return this._andWait(this.runPrivileged, js);
   }
 
   /**

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

@@ -0,0 +1,114 @@
+import { getLogger } from '@sitespeed.io/log';
+import { lcpHighlightScript as highlightLargestContentfulPaint } from '../util/lcpHighlightScript.js';
+import { clsHighlightScript as highlightLS } from '../util/lsHighlightScript.js';
+const log = getLogger('browsertime.command.measure');
+
+/**
+ * Handles screenshot capture during measurement collection.
+ * @class
+ * @private
+ */
+export class MeasureScreenshots {
+  constructor(browser, screenshotManager, options) {
+    this.browser = browser;
+    this.screenshotManager = screenshotManager;
+    this.options = options;
+  }
+
+  async afterPageCompleteCheck(url, index) {
+    if (!this.options.screenshot) {
+      return;
+    }
+    log.info('Take after page complete check screenshot');
+    try {
+      const screenshot = await this.browser.takeScreenshot(url);
+      await this.screenshotManager.save(
+        'afterPageCompleteCheck',
+        screenshot,
+        url,
+        index
+      );
+    } catch {
+      // not getting screenshots shouldn't result in a failed test.
+    }
+  }
+
+  async layoutShift(url, index) {
+    if (!this.options.screenshotLS) {
+      return;
+    }
+
+    const supportLS = await this.browser.runScript(
+      `
+      const supported = PerformanceObserver.supportedEntryTypes;
+      if (!supported || supported.indexOf('layout-shift') === -1) {
+        return false;
+      } else return true;
+      `,
+      'SUPPORT_LS'
+    );
+
+    if (!supportLS) {
+      return;
+    }
+
+    log.info('Take cumulative layout shift screenshot');
+    await this.browser.runScript(highlightLS, 'HIGHLIGHT_LS', {
+      color: this.options.screenshotLSColor || 'red',
+      limit: this.options.screenshotLSLimit || 0.01
+    });
+    const screenshot = await this.browser.takeScreenshot(url);
+    await this.screenshotManager.save('layoutShift', screenshot, url, index);
+    const lsScriptClean = `
+        const c = document.getElementById("browsertime-ls");
+        if (c) c.remove();
+      `;
+    await this.browser.runScript(lsScriptClean, 'CLEAN_LS');
+  }
+
+  async largestContentfulPaint(url, index) {
+    if (!this.options.screenshotLCP) {
+      return;
+    }
+
+    const supportLCP = await this.browser.runScript(
+      `
+      const supported = PerformanceObserver.supportedEntryTypes;
+      if (!supported || supported.indexOf('largest-contentful-paint') === -1) {
+        return false;
+      } else return true;
+      `,
+      'SUPPORT_LCP'
+    );
+
+    if (!supportLCP) {
+      return;
+    }
+
+    log.info('Take largest contentful paint screenshot');
+    try {
+      const lcpScriptClean = `
+        const c = document.getElementById("browsertime-lcp");
+        if (c) c.remove();
+      `;
+      const message = await this.browser.runScript(
+        highlightLargestContentfulPaint,
+        'HIGHLIGHT_LCP',
+        this.options.screenshotLCPColor || 'red'
+      );
+      if (message != '') {
+        log.info(message);
+      }
+      const screenshot = await this.browser.takeScreenshot(url);
+      await this.screenshotManager.save(
+        'largestContentfulPaint',
+        screenshot,
+        url,
+        index
+      );
+      await this.browser.runScript(lcpScriptClean, 'CLEAN_LCP');
+    } catch (error) {
+      log.error('Could not get LCP screenshot', error);
+    }
+  }
+}

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

@@ -0,0 +1,85 @@
+import { Video } from '../../../../video/video.js';
+import { setOrangeBackground } from '../../../../video/screenRecording/setOrangeBackground.js';
+import { isAndroidConfigured } from '../../../../android/index.js';
+import { getProperty } from '../../../../support/util.js';
+const delay = ms => new Promise(res => setTimeout(res, ms));
+
+/**
+ * Handles video recording during measurement.
+ * @class
+ * @private
+ */
+export class MeasureVideo {
+  constructor(storageManager, browser, videos, options) {
+    this.storageManager = storageManager;
+    this.browser = browser;
+    this.videos = videos;
+    this.options = options;
+    this.recordVideo = options.visualMetrics || options.video;
+    this.ANDROID_DELAY_TIME = getProperty(
+      options,
+      'orangeAndroidDelayTime',
+      2000
+    );
+    this.IOS_DELAY_TIME = getProperty(options, 'orangeIosDelayTime', 1000);
+    this.DESKTOP_DELAY_TIME = getProperty(
+      options,
+      'orangeDesktopDelayTime',
+      800
+    );
+  }
+
+  async start(numberOfMeasuredPages, index) {
+    this.video = new Video(this.storageManager, this.options, this.browser);
+
+    if (this.options.firefox && this.options.firefox.windowRecorder) {
+      // The Firefox window recorder will only record subsequent
+      // changes after recording has begun.  So the orange frame needs
+      // to come after we start recording.
+      await this.video.record(numberOfMeasuredPages, index);
+      await setOrangeBackground(this.browser.getDriver(), this.options);
+    } else {
+      await setOrangeBackground(this.browser.getDriver(), this.options);
+      await this.video.record(numberOfMeasuredPages, index);
+    }
+
+    // Give ffmpeg/video on phone time to settle
+    if (isAndroidConfigured(this.options)) {
+      return delay(this.ANDROID_DELAY_TIME);
+    } else if (this.options.safari && this.options.safari.ios) {
+      return delay(this.IOS_DELAY_TIME);
+    } else if (this.options.safari && this.options.safari.useSimulator) {
+      return delay(this.IOS_DELAY_TIME);
+    } else {
+      return delay(this.DESKTOP_DELAY_TIME);
+    }
+  }
+
+  async stop(url) {
+    if (this.recordVideo && !this.options.videoParams.debug) {
+      await this.video.stop(url);
+      this.videos.push(this.video);
+    }
+  }
+
+  getRecordingMetadata() {
+    if (
+      this.recordVideo &&
+      !this.options.videoParams.debug &&
+      this.video &&
+      this.video.getRecordingStartTime()
+    ) {
+      return {
+        recordingStartTime: Number.parseFloat(
+          this.video.getRecordingStartTime()
+        ),
+        timeToFirstFrame: Number.parseInt(this.video.getTimeToFirstFrame(), 10)
+      };
+    }
+    return;
+  }
+
+  shouldRecord() {
+    return this.recordVideo && !this.options.videoParams.debug;
+  }
+}