browsertime 20.0.0 → 21.1.0

package/lib/core/engine/commands.js

@@ -0,0 +1,267 @@
+import { Actions } from './command/actions.js';
+import { AddText } from './command/addText.js';
+import { Click } from './command/click.js';
+import { Element } from './command/element.js';
+import { Wait } from './command/wait.js';
+import { Measure } from './command/measure.js';
+import { JavaScript } from './command/javaScript.js';
+import { Switch } from './command/switch.js';
+import { Screenshot } from './command/screenshot.js';
+import { Set } from './command/set.js';
+import { Cache } from './command/cache.js';
+import { Meta } from './command/meta.js';
+import { Watch as StopWatch } from './command/stopWatch.js';
+import { Select } from './command/select.js';
+import { Debug } from './command/debug.js';
+import { AndroidCommand } from './command/android.js';
+import { ChromeDevelopmentToolsProtocol } from './command/chromeDevToolsProtocol.js';
+import { ChromeTrace } from './command/chromeTrace.js';
+import {
+  SingleClick,
+  DoubleClick,
+  ClickAndHold,
+  ContextClick,
+  MouseMove
+} from './command/mouse/index.js';
+import { Scroll } from './command/scroll.js';
+import { Navigation } from './command/navigation.js';
+import { GeckoProfiler } from '../../firefox/geckoProfiler.js';
+import { GeckoProfiler as GeckoProfilerCommand } from './command/geckoProfiler.js';
+/**
+ * Represents the set of commands available in a Browsertime script.
+ * @hideconstructor
+ */
+export class Commands {
+  constructor(
+    browser,
+    engineDelegate,
+    index,
+    result,
+    storageManager,
+    pageCompleteCheck,
+    extensionServer,
+    context,
+    videos,
+    screenshotManager,
+    scriptsByCategory,
+    asyncScriptsByCategory,
+    postURLScripts,
+    options
+  ) {
+    const measure = new Measure(
+      browser,
+      index,
+      pageCompleteCheck,
+      result,
+      engineDelegate,
+      extensionServer,
+      storageManager,
+      videos,
+      scriptsByCategory,
+      asyncScriptsByCategory,
+      postURLScripts,
+      context,
+      screenshotManager,
+      options
+    );
+
+    const browserProfiler = new GeckoProfiler(browser, storageManager, options);
+    // Profiler
+    this.profiler = new GeckoProfilerCommand(
+      browserProfiler,
+      browser,
+      index,
+      options,
+      result
+    );
+    const cdp = new ChromeDevelopmentToolsProtocol(
+      engineDelegate,
+      options.browser
+    );
+
+    /**
+     * Manages Chrome trace functionality, enabling custom profiling and trace collection in Chrome.
+     * @type {ChromeTrace}
+     */
+    this.trace = new ChromeTrace(engineDelegate, index, options, result);
+
+    /**
+     * Provides functionality to perform click actions on elements in a web page using various selectors.
+     * @type {Click}
+     */
+    this.click = new Click(browser, pageCompleteCheck);
+
+    /**
+     * Provides functionality to control page scrolling in the browser.
+     * @type {Scroll}
+     */
+    this.scroll = new Scroll(browser, options);
+
+    /**
+     * Provides functionality to add text to elements on a web page using various selectors.
+     * @type {AddText}
+     */
+    this.addText = new AddText(browser);
+
+    /**
+     * Provides functionality to wait for different conditions in the browser.
+     * @type {Wait}
+     */
+    this.wait = new Wait(browser, pageCompleteCheck);
+
+    /**
+     * Provides functionality for measuring a navigation.
+     * @type {Measure}
+     */
+    this.measure = measure;
+
+    /**
+     * Navigates to a specified URL and handles additional setup for a page visit.
+     * @async
+     * @example await commands.navigate('https://www.example.org');
+     * @type {Function}
+     * @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
+     */
+    this.navigate = measure._navigate.bind(measure);
+
+    /**
+     *  Provides functionality to control browser navigation such as back, forward, and refresh actions.
+     * @type {Navigation}
+     */
+    this.navigation = new Navigation(browser, pageCompleteCheck);
+
+    /**
+     * Add a text that will be an error attached to the current page.
+     * @example await commands.error('My error message');
+     * @param {string} message - The error message.
+     * @type {Function}
+     */
+    this.error = measure._error.bind(measure);
+
+    /**
+     * Mark this run as an failure. Add a message that explains the failure.
+     * @example await commands.markAsFailure('My failure message');
+     * @param {string} message - The message attached as a failure
+     * @type {Function}
+     */
+    this.markAsFailure = measure._failure.bind(measure);
+
+    /**
+     * Executes JavaScript in the browser context.
+     * @type {JavaScript}
+     */
+    this.js = new JavaScript(browser, pageCompleteCheck);
+
+    /**
+     * Switches context to different frames, windows, or tabs in the browser.
+     * @type {Switch}
+     */
+    this.switch = new Switch(
+      browser,
+      pageCompleteCheck,
+      measure._navigate.bind(measure)
+    );
+
+    /**
+     * Sets values on HTML elements in the page.
+     * @type {Set}
+     */
+    this.set = new Set(browser);
+
+    /**
+     * Stopwatch utility for measuring time intervals.
+     * @type {StopWatch}
+     */
+    this.stopWatch = new StopWatch(measure);
+
+    /**
+     * Manages the browser's cache.
+     * @type {Cache}
+     */
+    this.cache = new Cache(browser, options.browser, extensionServer, cdp);
+
+    /**
+     * Adds metadata to the user journey.
+     * @type {Meta}
+     */
+    this.meta = new Meta();
+
+    /**
+     * Takes and manages screenshots.
+     * @type {Screenshot}
+     */
+    this.screenshot = new Screenshot(screenshotManager, browser, index);
+
+    /**
+     * Use the Chrome DevTools Protocol, available in Chrome and Edge.
+     * @type {ChromeDevelopmentToolsProtocol}
+     */
+    this.cdp = cdp;
+
+    /**
+     * Provides commands for interacting with an Android device.
+     * @type {AndroidCommand}
+     */
+    this.android = new AndroidCommand(options);
+
+    /**
+     * Provides debugging capabilities within a browser automation script.
+     * It allows setting breakpoints to pause script execution and inspect the current state.
+     *  @type {Debug}
+     */
+    this.debug = new Debug(browser, options);
+
+    /**
+     * Interact with the page using the mouse.
+     * @type {Object}
+     */
+    this.mouse = {
+      /**
+       *  Move the mouse cursor to elements or specific positions on a web page.
+       * @type {MouseMove}
+       */
+      moveTo: new MouseMove(browser),
+      /**
+       *  Perform a context click (right-click) on elements in a web page.
+       * @type {ContextClick}
+       */
+      contextClick: new ContextClick(browser),
+      /**
+       *  Provides functionality to perform a single click action on elements or at specific positions in a web page.
+       * @type {SingleClick}
+       */
+      singleClick: new SingleClick(browser, pageCompleteCheck),
+      /**
+       *  Provides functionality to perform a double-click action on elements in a web page.
+       * @type {DoubleClick}
+       */
+      doubleClick: new DoubleClick(browser, pageCompleteCheck),
+      /**
+       *  Provides functionality to click and hold elements on a web page using different strategies.
+       * @type {ClickAndHold}
+       */
+      clickAndHold: new ClickAndHold(browser)
+    };
+
+    /**
+     * Interact with a select element.
+     * @type {Select}
+     */
+    this.select = new Select(browser);
+
+    /**
+     * Selenium's action sequence functionality.
+     * @type {Actions}
+     * @see https://www.selenium.dev/documentation/webdriver/actions_api/
+     */
+    this.action = new Actions(browser);
+
+    /**
+     * Get Selenium's WebElements.
+     * @type {Element}
+     */
+    this.element = new Element(browser);
+  }
+}

package/lib/core/engine/context.js

@@ -0,0 +1,81 @@
+/**
+ * @typedef {Object} Logger
+ * @property {function(string): void} trace - Function to log trace messages.
+ * @property {function(string): void} verbose - Function to log verbose messages.
+ * @property {function(string): void} info - Function to log info messages.
+ * @property {function(string): void} warn - Function to log warning messages.
+ * @property {function(string): void} error - Function to log error messages.
+ * @property {function(string): void} critical - Function to log critical messages.
+ */
+
+/**
+ * @typedef {typeof import('selenium-webdriver')} WebDriverClass
+ * @typedef {import('selenium-webdriver').WebDriver} WebDriverInstance
+ */
+
+/**
+ * Class representing the context of a Browsertime run.
+ * @hideconstructor
+ * @class
+ */
+export class Context {
+  constructor(
+    options,
+    result,
+    log,
+    storageManager,
+    index,
+    webdriver,
+    instantiatedDriver
+  ) {
+    /**
+     * This is the yargs object you get from the cli. If you add --my.id you can get that using options.my.id.
+     * @type {Object}
+     */
+    this.options = options;
+
+    /**
+     * Here the result from each run is stored.
+     * @type {Object}
+     */
+    this.result = result;
+
+    /**
+     * @type {Logger}
+     */
+    this.log = log;
+
+    /**
+     * The index of the iteration.
+     * @type {number}
+     */
+    this.index = index;
+
+    /**
+     * Storage manager to save things to disk.
+     * @type {import('../../support/storageManager.js').StorageManager}
+     */
+    this.storageManager = storageManager;
+
+    /**
+     * @type {Object}
+     */
+    this.taskData = {};
+
+    /**
+     * Get raw Selenium functionality.
+     * @see https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/index.html
+     * @type {{webdriver: WebDriverClass, driver: WebDriverInstance}}
+     */
+    this.selenium = {
+      /**
+       * @typedef {typeof import('selenium-webdriver')} WebDriverClass
+       */
+      webdriver,
+      /**
+       * @typedef {import('selenium-webdriver').WebDriver} WebDriverInstance
+       */
+      driver: instantiatedDriver
+    };
+  }
+}

package/lib/core/engine/iteration.js

@@ -2,6 +2,8 @@ import { platform } from 'node:os';
 import webdriver from 'selenium-webdriver';
 import intel from 'intel';
 
+import { Context } from './context.js';
+import { Commands } from './commands.js';
 import { SeleniumRunner } from '../seleniumRunner.js';
 import { preURL } from '../../support/preURL.js';
 import { setResourceTimingBufferSize } from '../../support/setResourceTimingBufferSize.js';
@@ -9,41 +11,16 @@ import { ScreenshotManager } from '../../screenshot/index.js';
 import { ExtensionServer } from '../../extensionserver/index.js';
 import { Video } from '../../video/video.js';
 import { stop } from '../../support/stop.js';
-import { AddText } from './command/addText.js';
-import { Click } from './command/click.js';
-import { Wait } from './command/wait.js';
-import { Measure } from './command/measure.js';
-import { JavaScript } from './command/javaScript.js';
-import { Switch } from './command/switch.js';
-import { Screenshot } from './command/screenshot.js';
-import { Set } from './command/set.js';
-import { Cache } from './command/cache.js';
-import { Meta } from './command/meta.js';
-import { Watch as StopWatch } from './command/stopWatch.js';
-import { Select } from './command/select.js';
-import { Debug } from './command/debug.js';
-import { AndroidCommand } from './command/android.js';
-import { ChromeDevelopmentToolsProtocol } from './command/chromeDevToolsProtocol.js';
-import { ChromeTrace } from './command/chromeTrace.js';
+
 import {
   addConnectivity,
   removeConnectivity
 } from '../../connectivity/index.js';
 import { jsonifyVisualProgress } from '../../support/util.js';
 import { flushDNS } from '../../support/dns.js';
-import {
-  SingleClick,
-  DoubleClick,
-  ClickAndHold,
-  ContextClick,
-  MouseMove
-} from './command/mouse/index.js';
+
 import { getNumberOfRunningProcesses } from '../../support/processes.js';
 import { isAndroidConfigured, Android } from '../../android/index.js';
-import { Scroll } from './command/scroll.js';
-import { Navigation } from './command/navigation.js';
-import { GeckoProfiler } from '../../firefox/geckoProfiler.js';
-import { GeckoProfiler as GeckoProfilerCommand } from './command/geckoProfiler.js';
 const log = intel.getLogger('browsertime');
 const delay = ms => new Promise(res => setTimeout(res, ms));
 
@@ -118,93 +95,33 @@ export class Iteration {
       await engineDelegate.afterBrowserStart(browser);
 
       // The data we push to all selenium scripts
-      const context = {
-        // TODO we want to have the URL here so we can use scripts to login
-        // and then access the supplied URL
+      const context = new Context(
         options,
         result,
         log,
-        storageManager: this.storageManager,
-        taskData: {},
+        this.storageManager,
         index,
-        selenium: {
-          webdriver, // The Selenium WebDriver public API object https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/index.html
-          driver: browser.getDriver() // The instantiated version of the WebDriver https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_WebDriver.html
-        }
-      };
+        webdriver,
+        browser.getDriver()
+      );
 
-      const measure = new Measure(
+      const commands = new Commands(
         browser,
+        engineDelegate,
         index,
-        this.pageCompleteCheck,
         result,
-        engineDelegate,
-        extensionServer,
         this.storageManager,
+        this.pageCompleteCheck,
+        extensionServer,
+        context,
         videos,
+        screenshotManager,
         this.scriptsByCategory,
         this.asyncScriptsByCategory,
         this.postURLScripts,
-        context,
-        screenshotManager,
         options
       );
 
-      const browserProfiler = new GeckoProfiler(
-        browser,
-        this.storageManager,
-        this.options
-      );
-      const profiler = new GeckoProfilerCommand(
-        browserProfiler,
-        browser,
-        index,
-        this.options,
-        result
-      );
-      const cdp = new ChromeDevelopmentToolsProtocol(
-        engineDelegate,
-        options.browser
-      );
-      const trace = new ChromeTrace(engineDelegate, index, options, result);
-      const android = new Android(options);
-      const debug = new Debug(browser, options);
-      const commands = {
-        profiler: profiler,
-        trace: trace,
-        click: new Click(browser, this.pageCompleteCheck),
-        scroll: new Scroll(browser, options),
-        addText: new AddText(browser),
-        wait: new Wait(browser, this.pageCompleteCheck),
-        measure: measure,
-        navigate: measure._navigate.bind(measure),
-        navigation: new Navigation(browser, this.pageCompleteCheck),
-        error: measure._error.bind(measure),
-        markAsFailure: measure._failure.bind(measure),
-        js: new JavaScript(browser, this.pageCompleteCheck),
-        switch: new Switch(
-          browser,
-          this.pageCompleteCheck,
-          measure._navigate.bind(measure)
-        ),
-        set: new Set(browser),
-        stopWatch: new StopWatch(measure),
-        cache: new Cache(browser, options.browser, extensionServer, cdp),
-        meta: new Meta(),
-        screenshot: new Screenshot(screenshotManager, browser, index),
-        cdp,
-        android: new AndroidCommand(options),
-        debug: debug,
-        mouse: {
-          moveTo: new MouseMove(browser),
-          contextClick: new ContextClick(browser),
-          singleClick: new SingleClick(browser, this.pageCompleteCheck),
-          doubleClick: new DoubleClick(browser, this.pageCompleteCheck),
-          clickAndHold: new ClickAndHold(browser)
-        },
-        select: new Select(browser)
-      };
-
       // Safari can't load data:text URLs at startup, so you can either choose
       // your own URL or use the blank one
       const startURL =
@@ -223,7 +140,8 @@ export class Iteration {
       // browser to get ready
       if (isAndroidConfigured(options)) {
         await delay(ANDROID_DELAY_TIME);
-        batteryTemperature.start = await android.getTemperature();
+        this.android = new Android(options);
+        batteryTemperature.start = await this.android.getTemperature();
       }
 
       await delay(options.timeToSettle || 100);
@@ -270,7 +188,7 @@ export class Iteration {
 
       // if we are in debig mode we wait on a continue command
       if (options.debug) {
-        await debug.breakpoint('End-of-iteration');
+        await commands.debug.breakpoint('End-of-iteration');
       }
 
       if (options.browser === 'firefox' && options.debug) {
@@ -293,8 +211,8 @@ export class Iteration {
       await engineDelegate.afterBrowserStopped();
 
       if (isAndroidConfigured(options)) {
-        batteryTemperature.stop = await android.getTemperature();
-        await android.removeDevtoolsFw();
+        batteryTemperature.stop = await this.android.getTemperature();
+        await this.android.removeDevtoolsFw();
       }
 
       if (options.visualMetrics && !options.videoParams.debug) {

package/lib/firefox/geckoProfiler.js

@@ -8,6 +8,26 @@ import { BrowserError } from '../support/errors.js';
 const delay = ms => new Promise(res => setTimeout(res, ms));
 const log = intel.getLogger('browsertime.firefox');
 
+// Return power usage in Wh
+function computePowerSum(counter) {
+  let sum = 0;
+  // Older Firefoxes see https://github.com/sitespeedio/sitespeed.io/issues/3944#issuecomment-1871090793
+  if (counter.sample_groups) {
+    for (const groups of counter.sample_groups) {
+      const countIndex = groups.samples.schema.count;
+      for (const sample of groups.samples.data) {
+        sum += sample[countIndex];
+      }
+    }
+  } else {
+    const countIndex = counter.samples.schema.count;
+    for (const sample of counter.samples.data) {
+      sum += sample[countIndex];
+    }
+  }
+  return sum * 1e-12;
+}
+
 /**
  * Timeout a promise after ms. Use promise.race to compete
  * about the timeout and the promise.
@@ -130,7 +150,7 @@ export class GeckoProfiler {
     return delay(firefoxConfig.geckoProfilerSettleTime || 3000);
   }
 
-  async stop(index, url) {
+  async stop(index, url, result) {
     const runner = this.runner;
     const storageManager = this.storageManager;
     const options = this.options;
@@ -183,6 +203,34 @@ export class GeckoProfiler {
         await android._downloadFile(deviceProfileFilename, destinationFilename);
       }
 
+      if (this.firefoxConfig.powerConsumption === true) {
+        const chosenFeatures = get(
+          this.firefoxConfig,
+          'geckoProfilerParams.features',
+          geckoProfilerDefaults.features
+        );
+        if (chosenFeatures.includes('power')) {
+          log.info('Collecting CPU power consumtion');
+          const profile = JSON.parse(
+            await storageManager.readData(
+              `geckoProfile-${index}.json`,
+              join(pathToFolder(url, options))
+            )
+          );
+          let power = 0;
+          for (const counter of profile.counters) {
+            if (counter.category === 'power') {
+              power += computePowerSum(counter);
+            }
+          }
+          result.powerConsumption = Number(power);
+        } else {
+          log.warning(
+            'Missing power setting in geckoProfilerParams.features so power will not be collected'
+          );
+        }
+      }
+
       // GZIP the profile and remove the old file
       log.info('Gzip file the profile.');
       const name = this.options.enableProfileRun

package/lib/firefox/webdriver/builder.js

@@ -55,15 +55,10 @@ export async function configureBuilder(builder, baseDir, options) {
 
   const ffOptions = new Options();
 
-  const profileTemplatePath = resolve(
-    moduleRootPath,
-    'browsersupport',
-    'firefox-profile'
-  );
-
-  ffOptions.setProfile(
-    get(firefoxConfig, 'profileTemplate') || profileTemplatePath
-  );
+  const profileTemplate = get(firefoxConfig, 'profileTemplate');
+  if (profileTemplate) {
+    ffOptions.setProfile(get(firefoxConfig, 'profileTemplate'));
+  }
 
   if (options.userAgent) {
     ffOptions.setPreference('general.useragent.override', options.userAgent);

package/lib/firefox/webdriver/firefox.js

@@ -140,7 +140,7 @@ export class Firefox {
       this.firefoxConfig.geckoProfiler &&
       this.firefoxConfig.geckoProfilerRecordingType !== 'custom'
     ) {
-      await this.geckoProfiler.stop(index, url);
+      await this.geckoProfiler.stop(index, url, result);
     }
 
     if (this.firefoxConfig.perfStats) {

package/lib/support/cli.js

@@ -537,6 +537,13 @@ export function parseCommandLine() {
         'need to specify the logs you wish to gather.',
       group: 'firefox'
     })
+    .option('firefox.powerConsumption', {
+      type: 'boolean',
+      default: false,
+      describe:
+        'Enable power consumption collection (in Wh). To get the consumption you also need to set firefox.geckoProfilerParams.features to include power.',
+      group: 'firefox'
+    })
     .option('firefox.setMozLog', {
       describe:
         'Use in conjunction with firefox.collectMozLog to set MOZ_LOG to something ' +

package/lib/support/getViewPort.js

@@ -21,12 +21,17 @@ const sizeMap = {
   'Pixel 2': '412x732',
   'Pixel 2 XL': '412x824',
   iPad: '768x1024',
+  'iPad Mini': '768x1024',
+  'iPad Air': '820x1180',
   'iPad Pro': '1024x1366',
   'iPhone XR': '414x896',
   'iPhone SE': '377x668',
   'iPhone 12 Pro': '390x844',
+  'iPhone 14 Pro': '430x932',
   'Pixel 5': '394x852',
-  'Samsung Galaxy S8+': '412x846'
+  'Pixel 7': '412x916',
+  'Samsung Galaxy S8+': '412x846',
+  'Samsung Galaxy A51/71': '412x914'
 };
 
 export function getViewPort(options) {