browsertime 26.3.1 → 27.0.0

package/lib/safari/webdriver/safari.js

@@ -1,11 +1,25 @@
 // const log = require('intel').getLogger('browsertime.safari');
-import { execaCommand as command } from 'execa';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execaCommand as command, execa } from 'execa';
+import { getLogger } from '@sitespeed.io/log';
+import { SafariInspectorClient } from '../safariInspectorClient.js';
+import { WebkitToCdpAdapter } from '../webkitToCdpAdapter.js';
+import { getHar } from '../har.js';
+import { getEmptyHAR, mergeHars } from '../../support/har/index.js';
+
 const delay = ms => new Promise(res => setTimeout(res, ms));
+const log = getLogger('browsertime.safari');
 
 export class Safari {
   constructor(storageManager, options) {
     this.options = options;
     this.safariOptions = options.safari || {};
+    this.skipHar = options.skipHar || false;
+    this.hars = [];
+    this.aliasAndUrl = {};
+    this.inspectorClient = undefined;
+    this.adapter = undefined;
   }
 
   /**
@@ -13,21 +27,184 @@ export class Safari {
    */
   async beforeBrowserStart() {
     if (this.safariOptions.ios) {
+      // Start ios-capture server BEFORE safaridriver to keep CoreMediaIO active
+      if (this.options.video) {
+        // Wake the iPhone into screen-capture mode by asking QuickTime to
+        // open a new movie recording. cmiod only enumerates iOS devices
+        // for CMIO when something triggers it (historically QuickTime),
+        // so we drive QuickTime headlessly here to remove the manual step.
+        // Once ios-capture has grabbed the AVCaptureSession the device
+        // stays in mirror mode, so we quit QuickTime before safaridriver
+        // starts — leaving QT holding the device blocks safaridriver from
+        // opening a WebDriver session.
+        await this._primeIOSScreenCapture();
+        await this._startIOSCaptureServer();
+        await this._unprimeIOSScreenCapture();
+      }
+
       this.driverProcess = command(
         'safaridriver -p ' + this.options.safariDriverPort,
         {
           shell: true
         }
       );
-      return delay(2000);
+      await delay(2000);
+
+      // Start the inspector client for HAR capture
+      if (!this.skipHar) {
+        this.inspectorClient = new SafariInspectorClient(this.options);
+      }
+    }
+  }
+
+  /**
+   * Use AppleScript to launch QuickTime Player and open a new movie
+   * recording window. This is what wakes the connected iPhone into
+   * screen-capture mode so cmiod will surface it to ios-capture.
+   *
+   * QuickTime stays running for the rest of the test session — its
+   * default recording panel binds to the FaceTime camera, so it does
+   * not contend with ios-capture for the iPhone. We quit QT in
+   * afterBrowserStopped() once ios-capture has released the device.
+   *
+   * Best-effort: if osascript fails (e.g. Automation permission has
+   * not been granted), we fall through to ios-capture which will then
+   * emit its usual "no iOS device found" error and the user can fall
+   * back to opening QuickTime manually.
+   */
+  async _primeIOSScreenCapture() {
+    log.info(
+      'Opening QuickTime Player to wake the iPhone into screen-capture mode (make sure the device is plugged in and unlocked)'
+    );
+    // launch (not activate) keeps QT from stealing focus. After the
+    // recording window appears we minimise it to the Dock and try to
+    // hide the whole process via System Events. The System Events call
+    // requires Accessibility permission for osascript on first run; if
+    // it's denied we fall through to just the minimised window.
+    const script = `
+      tell application "QuickTime Player"
+        launch
+        delay 0.5
+        if (count of (documents whose name contains "Movie Recording")) is 0 then
+          new movie recording
+        end if
+        delay 0.3
+        try
+          set miniaturized of every window to true
+        end try
+      end tell
+      try
+        tell application "System Events"
+          set visible of process "QuickTime Player" to false
+        end tell
+      end try
+    `;
+    try {
+      await execa('osascript', ['-e', script], { timeout: 10_000 });
+      // Give cmiod a beat to enumerate the now-awake iPhone before
+      // ios-capture starts looking for it.
+      await delay(2000);
+    } catch (error) {
+      log.warn(
+        'Could not prime iOS screen capture via QuickTime: %s. ' +
+          'Open QuickTime Player → New Movie Recording manually before re-running.',
+        error.message
+      );
     }
   }
 
+  /**
+   * Quit QuickTime Player without saving — paired with
+   * _primeIOSScreenCapture(). Best-effort.
+   */
+  async _unprimeIOSScreenCapture() {
+    try {
+      await execa(
+        'osascript',
+        ['-e', 'tell application "QuickTime Player" to quit saving no'],
+        { timeout: 5000 }
+      );
+    } catch {
+      // best-effort cleanup
+    }
+  }
+
+  /**
+   * Start the ios-capture server that enables CoreMediaIO and
+   * accepts START/STOP recording commands.
+   */
+  async _startIOSCaptureServer() {
+    const iosCaptureCommand = path.resolve(
+      path.dirname(new URL(import.meta.url).pathname),
+      '..',
+      'native',
+      'ios-capture'
+    );
+
+    log.debug('Starting ios-capture server');
+    this.iosCaptureProcess = execa(iosCaptureCommand, ['-r', '30'], {
+      stdin: 'pipe',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      reject: false
+    });
+
+    this.iosCaptureProcess.stderr.on('data', data => {
+      log.debug('ios-capture: %s', data.toString().trim());
+    });
+
+    this.iosCaptureProcess.catch(error => {
+      if (!error.isCanceled) {
+        log.error('ios-capture process ended: %s', error.message);
+      }
+    });
+
+    // Wait for READY signal
+    await new Promise((resolve, reject) => {
+      let buffer = '';
+      const handler = data => {
+        buffer += data.toString();
+        if (buffer.includes('READY')) {
+          this.iosCaptureProcess.stdout.removeListener('data', handler);
+          resolve();
+        }
+        if (buffer.includes('ERROR')) {
+          this.iosCaptureProcess.stdout.removeListener('data', handler);
+          reject(new Error(`ios-capture: ${buffer.trim()}`));
+        }
+      };
+      this.iosCaptureProcess.stdout.on('data', handler);
+      setTimeout(
+        () => reject(new Error('ios-capture server startup timeout')),
+        15_000
+      );
+    });
+
+    // Store the process on options so the IOSDeviceRecorder can access it
+    this.options._iosCaptureProcess = this.iosCaptureProcess;
+    log.debug('ios-capture server ready');
+  }
+
   /**
    * The browser is up and running, now its time to start to
    * configure what you need.
    */
-  async afterBrowserStart() {}
+  async afterBrowserStart(runner) {
+    if (this.safariOptions.ios && this.inspectorClient) {
+      // iWDP exposes every open Safari tab on the device, not just the one
+      // safaridriver controls. Drive the WebDriver tab to a unique sentinel
+      // URL so the inspector can identify and pin it; otherwise an unrelated
+      // tab's Target.targetCreated may clobber the active target and the HAR
+      // comes back empty.
+      const sentinel = `data:text/html;charset=utf-8,<title>browsertime-${randomUUID()}</title>`;
+      try {
+        await runner.getDriver().get(sentinel);
+      } catch (error) {
+        log.debug('Failed to navigate to sentinel URL: %s', error.message);
+      }
+      await this.inspectorClient.setup(page => page.url === sentinel);
+    }
+  }
 
   /**
    * Before the first iteration of your tests start.
@@ -37,7 +214,36 @@ export class Safari {
   /**
    * Before each URL/test runs.
    */
-  async beforeEachURL() {}
+  async beforeEachURL() {
+    if (this.inspectorClient) {
+      this.adapter = new WebkitToCdpAdapter();
+      this.inspectorClient.removeAllListeners();
+
+      // Register listeners for all network and page events
+      const networkEvents = [
+        'Network.requestWillBeSent',
+        'Network.responseReceived',
+        'Network.dataReceived',
+        'Network.loadingFinished',
+        'Network.loadingFailed',
+        'Network.requestServedFromMemoryCache',
+        'Page.loadEventFired',
+        'Page.domContentEventFired'
+      ];
+      for (const event of networkEvents) {
+        this.inspectorClient.on(event, params => {
+          this.adapter.onWebkitEvent(event, params);
+        });
+      }
+
+      // Reconnect to iwdp to pick up any new pages after safaridriver setup
+      try {
+        await this.inspectorClient.reconnect();
+      } catch (error) {
+        log.debug('Reconnect attempt: %s', error.message);
+      }
+    }
+  }
 
   /**
    * When the page has finsihed loading, this functions runs (before
@@ -45,19 +251,44 @@ export class Safari {
    * stop trace logging, stop measuring etc.
    *
    */
-  async afterPageCompleteCheck(runner) {
+  async afterPageCompleteCheck(runner, index, url, alias) {
     const resources = await runner.runScript(
       'return performance.getEntriesByType("resource");',
       'RESOURCE_TIMINGS'
     );
 
-    return {
+    const result = {
       browserScripts: {
         timings: {
           resourceTimings: resources
         }
-      }
+      },
+      url,
+      alias
     };
+
+    // Collect HAR from inspector client
+    if (this.inspectorClient && this.adapter) {
+      try {
+        const har = await getHar(
+          this.adapter,
+          result,
+          index,
+          this.inspectorClient,
+          this.safariOptions.includeResponseBodies,
+          this.aliasAndUrl,
+          this.options.cleanSensitiveHeaders
+        );
+        if (har.log.entries.length > 0) {
+          this.hars.push(har);
+          log.debug('Captured HAR with %d entries', har.log.entries.length);
+        }
+      } catch (error) {
+        log.error('Failed to generate HAR: %s', error.message);
+      }
+    }
+
+    return result;
   }
 
   /**
@@ -68,19 +299,31 @@ export class Safari {
   /**
    * This method is called if a runs fail
    */
-  failing() {}
+  failing(url) {
+    if (!this.skipHar) {
+      this.hars.push(getEmptyHAR(url, 'Safari'));
+    }
+  }
 
   /**
    * Get the HAR file for all the runs.
    */
   async getHARs() {
-    return [];
+    if (this.hars.length > 0) {
+      return { har: mergeHars(this.hars) };
+    }
+    return {};
   }
 
   /**
    * Before the browser is stopped/closed.
    */
-  async beforeBrowserStop() {}
+  async beforeBrowserStop() {
+    if (this.inspectorClient) {
+      await this.inspectorClient.close();
+      this.inspectorClient = undefined;
+    }
+  }
 
   async afterBrowserStopped() {
     if (this.safariOptions.useSimulator) {
@@ -92,12 +335,59 @@ export class Safari {
       );
     }
 
-    if (this.safariOptions.ios) {
-      await this.driverProcess.kill('SIGINT');
+    if (this.safariOptions.ios && this.driverProcess) {
+      const driverProc = this.driverProcess;
+      this.driverProcess = undefined;
+      try {
+        driverProc.kill('SIGINT');
+      } catch {
+        // Already dead
+      }
+    }
+
+    // Stop ios-capture server: send QUIT, then wait for it to exit and
+    // release the AVCaptureSession on the iPhone. If we don't wait, the
+    // device can stay locked in CMIO until something else evicts it,
+    // which breaks subsequent runs (and even QuickTime).
+    if (this.iosCaptureProcess) {
+      const proc = this.iosCaptureProcess;
+      this.iosCaptureProcess = undefined;
+      try {
+        proc.stdin.write('QUIT\n');
+      } catch {
+        // stdin already closed
+      }
+      try {
+        await Promise.race([
+          proc,
+          new Promise((_, reject) =>
+            setTimeout(
+              () => reject(new Error('ios-capture exit timeout')),
+              5000
+            )
+          )
+        ]);
+      } catch {
+        try {
+          proc.kill('SIGTERM');
+          await Promise.race([
+            proc,
+            new Promise((_, reject) =>
+              setTimeout(() => reject(new Error('SIGTERM timeout')), 2000)
+            )
+          ]);
+        } catch {
+          try {
+            proc.kill('SIGKILL');
+          } catch {
+            // Ignore
+          }
+        }
+      }
     }
   }
 
   async waitForNetworkIdle() {
-    throw new Error('waitForNetworkIdle is not implemented in Safari');
+    throw new Error('waitForNetworkIdle is not yet implemented for Safari');
   }
 }

package/lib/safari/webkitToCdpAdapter.js

@@ -0,0 +1,241 @@
+import { getLogger } from '@sitespeed.io/log';
+
+const log = getLogger('browsertime.safari.adapter');
+
+/**
+ * Adapts WebKit Inspector Protocol network events to Chrome DevTools Protocol
+ * format so they can be processed by chrome-har.
+ */
+export class WebkitToCdpAdapter {
+  constructor() {
+    this.messages = [];
+    this.responseMap = new Map();
+    this.requestTimestamps = new Map(); // requestId -> { timestamp, wallTime }
+    this.mainFrameId = undefined;
+    this.pageCreated = false;
+  }
+
+  onWebkitEvent(method, params) {
+    switch (method) {
+      case 'Network.requestWillBeSent': {
+        const adapted = this._adaptRequestWillBeSent(params);
+
+        // chrome-har needs a Page.frameNavigated event to create a page.
+        // Inject it when we see the first Document request.
+        if (!this.pageCreated && adapted.type === 'Document') {
+          this.mainFrameId = adapted.frameId || 'main';
+          this.messages.push({
+            method: 'Page.frameStartedLoading',
+            params: {
+              frameId: this.mainFrameId
+            }
+          });
+          this.pageCreated = true;
+        }
+
+        this.messages.push({
+          method: 'Network.requestWillBeSent',
+          params: adapted
+        });
+        break;
+      }
+      case 'Network.responseReceived': {
+        const adapted = {
+          method: 'Network.responseReceived',
+          params: this._adaptResponseReceived(params)
+        };
+        this.messages.push(adapted);
+        this.responseMap.set(params.requestId, adapted);
+        break;
+      }
+      case 'Network.dataReceived': {
+        this.messages.push({
+          method: 'Network.dataReceived',
+          params: {
+            requestId: params.requestId,
+            timestamp: params.timestamp,
+            dataLength: params.dataLength,
+            encodedDataLength: params.encodedDataLength || 0
+          }
+        });
+        break;
+      }
+      case 'Network.loadingFinished': {
+        this._patchResponseWithMetrics(params);
+        this.messages.push({
+          method: 'Network.loadingFinished',
+          params: {
+            requestId: params.requestId,
+            timestamp: params.timestamp,
+            encodedDataLength:
+              params.metrics?.responseBodyBytesReceived ??
+              params.encodedDataLength ??
+              0
+          }
+        });
+        break;
+      }
+      case 'Network.loadingFailed': {
+        this.messages.push({
+          method: 'Network.loadingFailed',
+          params: {
+            requestId: params.requestId,
+            timestamp: params.timestamp,
+            errorText: params.errorText || 'Failed',
+            canceled: params.canceled || false,
+            type: params.type
+          }
+        });
+        break;
+      }
+      case 'Network.requestServedFromMemoryCache': {
+        this.messages.push({
+          method: 'Network.requestServedFromMemoryCache',
+          params
+        });
+        break;
+      }
+      case 'Page.loadEventFired': {
+        this.messages.push({
+          method: 'Page.loadEventFired',
+          params: { timestamp: params.timestamp }
+        });
+        break;
+      }
+      case 'Page.domContentEventFired': {
+        this.messages.push({
+          method: 'Page.domContentEventFired',
+          params: { timestamp: params.timestamp }
+        });
+        break;
+      }
+      default: {
+        log.debug('Unhandled WebKit event: %s', method);
+      }
+    }
+  }
+
+  _adaptRequestWillBeSent(params) {
+    // Store timestamp mapping for converting timing.requestTime to epoch-relative
+    this.requestTimestamps.set(params.requestId, {
+      timestamp: params.timestamp,
+      wallTime: params.walltime || params.wallTime || Date.now() / 1000
+    });
+
+    return {
+      requestId: params.requestId,
+      frameId: params.frameId,
+      loaderId: params.loaderId || params.requestId,
+      documentURL: params.documentURL || '',
+      timestamp: params.timestamp,
+      wallTime: params.walltime || params.wallTime || Date.now() / 1000,
+      type: params.type,
+      initiator: params.initiator || { type: 'other' },
+      request: {
+        url: params.request?.url || '',
+        method: params.request?.method || 'GET',
+        headers: params.request?.headers || {},
+        postData: params.request?.postData,
+        initialPriority: 'Medium'
+      },
+      redirectResponse: params.redirectResponse
+        ? this._adaptResponse(params.redirectResponse)
+        : undefined
+    };
+  }
+
+  _adaptResponseReceived(params) {
+    return {
+      requestId: params.requestId,
+      frameId: params.frameId,
+      loaderId: params.loaderId || params.requestId,
+      timestamp: params.timestamp,
+      type: params.type,
+      response: this._adaptResponse(params.response || {})
+    };
+  }
+
+  _adaptResponse(response) {
+    const timing = response.timing
+      ? this._adaptTiming(response.timing)
+      : undefined;
+
+    return {
+      url: response.url || '',
+      status: response.status || 0,
+      statusText: response.statusText || '',
+      headers: response.headers || {},
+      mimeType: response.mimeType || '',
+      connectionId: String(response.connectionId || '0'),
+      remoteIPAddress: response.remoteIPAddress || '',
+      remotePort: response.remotePort || 0,
+      protocol: response.protocol || '',
+      encodedDataLength: response.encodedDataLength || 0,
+      fromDiskCache:
+        response.source === 'disk-cache' ||
+        response.source === 'memory-cache' ||
+        response.fromDiskCache === true,
+      fromServiceWorker: response.source === 'service-worker' || false,
+      timing
+    };
+  }
+
+  _adaptTiming(timing) {
+    // WebKit timing fields are ms offsets from fetchStart, similar to CDP
+    // but secureConnectionStart can be an absolute timestamp when reused
+    let sslStart = timing.secureConnectionStart ?? -1;
+    let sslEnd = timing.connectEnd ?? -1;
+
+    // Detect invalid SSL timestamps (WebKit sends huge negative numbers for reused connections)
+    if (sslStart > 100_000 || sslStart < -1) {
+      sslStart = -1;
+      sslEnd = -1;
+    }
+
+    return {
+      // WebKit uses startTime (seconds, page-relative) as the request base time
+      requestTime: Number(timing.startTime) || 0,
+      dnsStart: Number(timing.domainLookupStart ?? -1),
+      dnsEnd: Number(timing.domainLookupEnd ?? -1),
+      connectStart: Number(timing.connectStart ?? -1),
+      connectEnd: Number(timing.connectEnd ?? -1),
+      sslStart: Number(sslStart),
+      sslEnd: Number(sslEnd),
+      sendStart: Number(timing.requestStart ?? -1),
+      sendEnd: Number(timing.requestStart ?? -1),
+      receiveHeadersEnd: Number(timing.responseStart ?? -1)
+    };
+  }
+
+  _patchResponseWithMetrics(loadingFinishedParams) {
+    const metrics = loadingFinishedParams.metrics;
+    if (!metrics) return;
+
+    const responseMsg = this.responseMap.get(loadingFinishedParams.requestId);
+    if (!responseMsg) return;
+
+    const response = responseMsg.params.response;
+    if (metrics.remoteAddress && !response.remoteIPAddress) {
+      const separator = metrics.remoteAddress.lastIndexOf(':');
+      response.remoteIPAddress =
+        separator === -1
+          ? metrics.remoteAddress
+          : metrics.remoteAddress.slice(0, separator);
+    }
+    if (metrics.protocol && !response.protocol) {
+      response.protocol = metrics.protocol;
+    }
+  }
+
+  getMessages() {
+    return [...this.messages];
+  }
+
+  reset() {
+    this.messages = [];
+    this.responseMap.clear();
+    this.requestTimestamps.clear();
+    this.pageCreated = false;
+    this.mainFrameId = undefined;
+  }
+}

package/lib/support/cli.js

@@ -194,6 +194,13 @@ export function parseCommandLine() {
         'Timeout when running pageCompleteCheckNetworkIdle, in milliseconds',
       group: 'timeouts'
     })
+    .option('timeouts.elementWait', {
+      default: 6000,
+      type: 'number',
+      describe:
+        'Timeout when waiting for an element to appear before interacting with it (click, addText etc), in milliseconds. Default is 6000 (6 seconds). Set to 0 to disable.',
+      group: 'timeouts'
+    })
     .option('chrome.args', {
       describe:
         'Extra command line arguments to pass to the Chrome process (e.g. --no-sandbox). ' +
@@ -905,6 +912,12 @@ export function parseCommandLine() {
       type: 'boolean',
       group: 'safari'
     })
+    .option('safari.includeResponseBodies', {
+      describe:
+        'Include response bodies in HAR for Safari iOS. "none" (default), "html", or "all".',
+      default: 'none',
+      group: 'safari'
+    })
     /** Screenshot */
     .option('screenshot', {
       type: 'boolean',

package/lib/support/engineUtils.js

@@ -19,17 +19,28 @@ async function loadFile(script, options, throwError) {
   // if the script is an AsyncFunction, return it.
   if (script instanceof AsyncFunction) {
     return script;
-  } else if (!script.endsWith('js')) {
+  } else if (!script.endsWith('js') && !script.endsWith('ts')) {
     // This is an inline script
     return script;
   }
-  // If we follow correct naming for modules (.mjs) or commonjs (.cjs)
-  // we just loads it. .js files is loaded as commonjs if you set
+
+  if (script.endsWith('ts')) {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major < 22 || (major === 22 && minor < 18)) {
+      throw new Error(
+        `TypeScript scripts require Node.js 22.18.0 or later. You are running ${process.versions.node}.`
+      );
+    }
+  }
+  // If we follow correct naming for modules (.mjs/.mts) or commonjs (.cjs/.cts)
+  // we just loads it. .js/.ts files is loaded as commonjs if you set
   // --cjs true
   if (
     options.cjs === false ||
     script.endsWith('.mjs') ||
-    script.endsWith('.cjs')
+    script.endsWith('.cjs') ||
+    script.endsWith('.mts') ||
+    script.endsWith('.cts')
   ) {
     let myFunction = await import(pathToFileURL(path.resolve(script)));
     return myFunction.default ?? myFunction;
@@ -90,7 +101,7 @@ export async function loadPrePostScripts(scripts, options) {
 }
 
 export async function loadPageCompleteScript(script) {
-  if (script && script.endsWith('js')) {
+  if (script && (script.endsWith('js') || script.endsWith('ts'))) {
     return readFile(path.resolve(script), 'utf8');
   }
   return script;