appium-remote-debugger 11.4.2 → 11.5.1

package/lib/mixins/message-handlers.js

@@ -1,6 +1,11 @@
-import log from '../logger';
 import events from './events';
-import { pageArrayFromDict, getDebuggerAppKey, simpleStringify, appInfoFromDict } from '../utils';
+import {
+  pageArrayFromDict,
+  getDebuggerAppKey,
+  simpleStringify,
+  appInfoFromDict,
+  deferredPromise,
+} from '../utils';
 import _ from 'lodash';
 
 
@@ -16,14 +21,14 @@ import _ from 'lodash';
  * @param {Record<string, any>} pageDict
  * @returns {Promise<void>}
  */
-async function onPageChange (err, appIdKey, pageDict) {
+export async function onPageChange (err, appIdKey, pageDict) {
   if (_.isEmpty(pageDict)) {
     return;
   }
 
   const pageArray = pageArrayFromDict(pageDict);
 
-  await this.useAppDictLock((done) => {
+  await useAppDictLock.bind(this)((/** @type {() => void} */ done) => {
     try {
       // save the page dict for this app
       if (this.appDict[appIdKey]) {
@@ -34,7 +39,7 @@ async function onPageChange (err, appIdKey, pageDict) {
           } else {
             // we have a pre-existing pageDict
             if (_.isEqual(this.appDict[appIdKey].pageArray, pageArray)) {
-              log.debug(`Received page change notice for app '${appIdKey}' ` +
+              this.log.debug(`Received page change notice for app '${appIdKey}' ` +
                         `but the listing has not changed. Ignoring.`);
               return done();
             }
@@ -53,7 +58,7 @@ async function onPageChange (err, appIdKey, pageDict) {
     return;
   }
 
-  log.debug(`Page changed: ${simpleStringify(pageDict, true)}`);
+  this.log.debug(`Page changed: ${simpleStringify(pageDict, true)}`);
 
   this.emit(events.EVENT_PAGE_CHANGE, {
     appIdKey: appIdKey.replace('PID:', ''),
@@ -67,12 +72,12 @@ async function onPageChange (err, appIdKey, pageDict) {
  * @param {Record<string, any>} dict
  * @returns {Promise<void>}
  */
-async function onAppConnect (err, dict) {
+export async function onAppConnect (err, dict) {
   const appIdKey = dict.WIRApplicationIdentifierKey;
-  log.debug(`Notified that new application '${appIdKey}' has connected`);
-  await this.useAppDictLock((/** @type {() => Void} */done) => {
+  this.log.debug(`Notified that new application '${appIdKey}' has connected`);
+  await useAppDictLock.bind(this)((/** @type {() => void} */ done) => {
     try {
-      this.updateAppsWithDict(dict);
+      updateAppsWithDict.bind(this)(dict);
     } finally {
       done();
     }
@@ -85,10 +90,10 @@ async function onAppConnect (err, dict) {
  * @param {Record<string, any>} dict
  * @returns {void}
  */
-function onAppDisconnect (err, dict) {
+export function onAppDisconnect (err, dict) {
   const appIdKey = dict.WIRApplicationIdentifierKey;
-  log.debug(`Application '${appIdKey}' disconnected. Removing from app dictionary.`);
-  log.debug(`Current app is '${this.appIdKey}'`);
+  this.log.debug(`Application '${appIdKey}' disconnected. Removing from app dictionary.`);
+ this.log.debug(`Current app is '${this.appIdKey}'`);
 
   // get rid of the entry in our app dictionary,
   // since it is no longer available
@@ -96,13 +101,13 @@ function onAppDisconnect (err, dict) {
 
   // if the disconnected app is the one we are connected to, try to find another
   if (this.appIdKey === appIdKey) {
-    log.debug(`No longer have app id. Attempting to find new one.`);
+    this.log.debug(`No longer have app id. Attempting to find new one.`);
     this.appIdKey = getDebuggerAppKey(/** @type {string} */ (this.bundleId), this.appDict);
   }
 
   if (!this.appDict) {
     // this means we no longer have any apps. what the what?
-    log.debug('Main app disconnected. Disconnecting altogether.');
+    this.log.debug('Main app disconnected. Disconnecting altogether.');
     this.connected = false;
     this.emit(events.EVENT_DISCONNECT, true);
   }
@@ -114,10 +119,10 @@ function onAppDisconnect (err, dict) {
  * @param {Record<string, any>} dict
  * @returns {Promise<void>}
  */
-async function onAppUpdate (err, dict) {
-  await this.useAppDictLock((done) => {
+export async function onAppUpdate (err, dict) {
+  await useAppDictLock.bind(this)((/** @type {() => void} */ done) => {
     try {
-      this.updateAppsWithDict(dict);
+      updateAppsWithDict.bind(this)(dict);
     } finally {
       done();
     }
@@ -130,9 +135,9 @@ async function onAppUpdate (err, dict) {
  * @param {Record<string, any>} drivers
  * @returns {void}
  */
-function onConnectedDriverList (err, drivers) {
+export function onConnectedDriverList (err, drivers) {
   this.connectedDrivers = drivers.WIRDriverDictionaryKey;
-  log.debug(`Received connected driver list: ${JSON.stringify(this.connectedDrivers)}`);
+  this.log.debug(`Received connected driver list: ${JSON.stringify(this.connectedDrivers)}`);
 }
 
 /**
@@ -141,11 +146,11 @@ function onConnectedDriverList (err, drivers) {
  * @param {Record<string, any>} state
  * @returns {void}
  */
-function onCurrentState (err, state) {
+export function onCurrentState (err, state) {
   this.currentState = state.WIRAutomationAvailabilityKey;
   // This state changes when 'Remote Automation' in 'Settings app' > 'Safari' > 'Advanced' > 'Remote Automation' changes
   // WIRAutomationAvailabilityAvailable or WIRAutomationAvailabilityNotAvailable
-  log.debug(`Received connected automation availability state: ${JSON.stringify(this.currentState)}`);
+  this.log.debug(`Received connected automation availability state: ${JSON.stringify(this.currentState)}`);
 }
 
 /**
@@ -154,8 +159,8 @@ function onCurrentState (err, state) {
  * @param {Record<string, any>} apps
  * @returns {Promise<void>}
  */
-async function onConnectedApplicationList (err, apps) {
-  log.debug(`Received connected applications list: ${_.keys(apps).join(', ')}`);
+export async function onConnectedApplicationList (err, apps) {
+  this.log.debug(`Received connected applications list: ${_.keys(apps).join(', ')}`);
 
   // translate the received information into an easier-to-manage
   // hash with app id as key, and app info as value
@@ -168,7 +173,7 @@ async function onConnectedApplicationList (err, apps) {
     newDict[id] = entry;
   }
   // update the object's list of apps
-  await this.useAppDictLock((done) => {
+  await useAppDictLock.bind(this)((/** @type {() => void} */ done) => {
     try {
       _.defaults(this.appDict, newDict);
     } finally {
@@ -177,14 +182,40 @@ async function onConnectedApplicationList (err, apps) {
   });
 }
 
-const messageHandlers = {
-  onPageChange,
-  onAppConnect,
-  onAppDisconnect,
-  onAppUpdate,
-  onConnectedDriverList,
-  onCurrentState,
-  onConnectedApplicationList,
-};
-
-export default messageHandlers;
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {(done: () => any) => any} fn
+ * @returns {Promise<any>}
+ */
+async function useAppDictLock (fn) {
+  return await this._lock.acquire('appDict', fn);
+}
+
+
+/**
+ *
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {import('@appium/types').StringRecord} dict
+ * @returns {void}
+ */
+function updateAppsWithDict (dict) {
+  // get the dictionary entry into a nice form, and add it to the
+  // application dictionary
+  this.appDict = this.appDict || {};
+  let [id, entry] = appInfoFromDict(dict);
+  if (this.appDict[id]) {
+    // preserve the page dictionary for this entry
+    entry.pageArray = this.appDict[id].pageArray;
+  }
+  this.appDict[id] = entry;
+
+  // add a promise to get the page dictionary
+  if (_.isUndefined(entry.pageArray)) {
+    entry.pageArray = deferredPromise();
+  }
+
+  // try to get the app id from our connected apps
+  if (!this.appIdKey) {
+    this.appIdKey = getDebuggerAppKey(/** @type {string} */ (this.bundleId), this.appDict);
+  }
+}

package/lib/mixins/misc.js

@@ -0,0 +1,128 @@
+import { checkParams } from '../utils';
+import B from 'bluebird';
+
+const SAFARI_BUNDLE_ID = 'com.apple.mobilesafari';
+const GARBAGE_COLLECT_TIMEOUT_MS = 5000;
+
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {Promise<void>}
+ */
+export async function launchSafari () {
+  await this.requireRpcClient().send('launchApplication', {
+    bundleId: SAFARI_BUNDLE_ID
+  });
+}
+
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {(event: import('@appium/types').StringRecord) => any} fn
+ * @returns {Promise<any>}
+ */
+export async function startTimeline (fn) {
+  this.log.debug('Starting to record the timeline');
+  this.requireRpcClient().on('Timeline.eventRecorded', fn);
+  return await this.requireRpcClient().send('Timeline.start', {
+    appIdKey: this.appIdKey,
+    pageIdKey: this.pageIdKey,
+  });
+}
+
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {Promise<any>}
+ */
+export async function stopTimeline () {
+  this.log.debug('Stopping to record the timeline');
+  await this.requireRpcClient().send('Timeline.stop', {
+    appIdKey: this.appIdKey,
+    pageIdKey: this.pageIdKey,
+  });
+}
+
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {(event: import('@appium/types').StringRecord) => any} listener
+ * @returns {void}
+ */
+export function startConsole (listener) {
+  this.log.debug('Starting to listen for JavaScript console');
+  this.addClientEventListener('Console.messageAdded', listener);
+  this.addClientEventListener('Console.messageRepeatCountUpdated', listener);
+}
+
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {void}
+ */
+export function stopConsole () {
+  this.log.debug('Stopping to listen for JavaScript console');
+  this.removeClientEventListener('Console.messageAdded');
+  this.removeClientEventListener('Console.messageRepeatCountUpdated');
+}
+
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {(event: import('@appium/types').StringRecord) => any} listener
+ * @returns {void}
+ */
+export function startNetwork (listener) {
+  this.log.debug('Starting to listen for network events');
+  this.addClientEventListener('NetworkEvent', listener);
+}
+
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {void}
+ */
+export function stopNetwork () {
+  this.log.debug('Stopping to listen for network events');
+  this.removeClientEventListener('NetworkEvent');
+}
+
+// Potentially this does not work for mobile safari
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {string} value
+ * @returns {Promise<any>}
+ */
+export async function overrideUserAgent (value) {
+  this.log.debug('Setting overrideUserAgent');
+  return await this.requireRpcClient().send('Page.overrideUserAgent', {
+    appIdKey: this.appIdKey,
+    pageIdKey: this.pageIdKey,
+    value
+  });
+}
+
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {number} [timeoutMs=GARBAGE_COLLECT_TIMEOUT_MS]
+ * @returns {Promise<void>}
+ */
+export async function garbageCollect (timeoutMs = GARBAGE_COLLECT_TIMEOUT_MS) {
+  this.log.debug(`Garbage collecting with ${timeoutMs}ms timeout`);
+
+  try {
+    checkParams({appIdKey: this.appIdKey, pageIdKey: this.pageIdKey});
+  } catch (err) {
+    this.log.debug(`Unable to collect garbage at this time`);
+    return;
+  }
+
+  try {
+    await B.resolve(this.requireRpcClient().send(
+      'Heap.gc', {
+        appIdKey: this.appIdKey,
+        pageIdKey: this.pageIdKey,
+      })
+    ).timeout(timeoutMs);
+    this.log.debug(`Garbage collection successful`);
+  } catch (e) {
+    if (e instanceof B.TimeoutError) {
+      this.log.debug(`Garbage collection timed out after ${timeoutMs}ms`);
+    } else {
+      this.log.debug(`Unable to collect garbage: ${e.message}`);
+    }
+  }
+}

package/lib/mixins/navigate.js

@@ -1,4 +1,3 @@
-import log from '../logger';
 import { checkParams } from '../utils';
 import events from './events';
 import { timing, util } from '@appium/support';
@@ -25,7 +24,7 @@ const PAGE_LOAD_STRATEGY = {
  * @this {import('../remote-debugger').RemoteDebugger}
  * @returns {void}
  */
-function frameDetached () {
+export function frameDetached () {
   this.emit(events.EVENT_FRAMES_DETACHED);
 }
 
@@ -33,8 +32,8 @@ function frameDetached () {
  * @this {import('../remote-debugger').RemoteDebugger}
  * @returns {void}
  */
-function cancelPageLoad () {
-  log.debug('Unregistering from page readiness notifications');
+export function cancelPageLoad () {
+  this.log.debug('Unregistering from page readiness notifications');
   this.pageLoading = false;
   if (this.pageLoadDelay) {
     this.pageLoadDelay.cancel();
@@ -48,7 +47,7 @@ function cancelPageLoad () {
  * @param {string} readyState
  * @returns {boolean}
  */
-function isPageLoadingCompleted (readyState) {
+export function isPageLoadingCompleted (readyState) {
   const _pageLoadStrategy = _.toLower(this.pageLoadStrategy);
   if (_pageLoadStrategy === PAGE_LOAD_STRATEGY.NONE) {
     return true;
@@ -65,14 +64,14 @@ function isPageLoadingCompleted (readyState) {
 
 /**
  * @this {import('../remote-debugger').RemoteDebugger}
- * @param {timing.Timer|null|undefined} startPageLoadTimer
+ * @param {timing.Timer?} [startPageLoadTimer]
  * @returns {Promise<void>}
  */
-async function waitForDom (startPageLoadTimer) {
-  log.debug('Waiting for page readiness');
+export async function waitForDom (startPageLoadTimer) {
+  this.log.debug('Waiting for page readiness');
   const readinessTimeoutMs = this.pageLoadMs || DEFAULT_PAGE_READINESS_TIMEOUT_MS;
   if (!_.isFunction(startPageLoadTimer?.getDuration)) {
-    log.debug(`Page load timer not a timer. Creating new timer`);
+    this.log.debug(`Page load timer not a timer. Creating new timer`);
     startPageLoadTimer = new timing.Timer().start();
   }
 
@@ -94,7 +93,7 @@ async function waitForDom (startPageLoadTimer) {
       await B.delay(intervalMs);
       // we can get this called in the middle of trying to find a new app
       if (!this.appIdKey) {
-        log.debug('Not connected to an application. Ignoring page readiess check');
+        this.log.debug('Not connected to an application. Ignoring page readiess check');
         return;
       }
       if (!isPageLoading) {
@@ -103,13 +102,13 @@ async function waitForDom (startPageLoadTimer) {
 
       if (await this.checkPageIsReady()) {
         if (isPageLoading) {
-          log.debug(`Page is ready in ${elapsedMs}ms`);
+          this.log.debug(`Page is ready in ${elapsedMs}ms`);
           isPageLoading = false;
         }
         return;
       }
       if (elapsedMs > readinessTimeoutMs) {
-        log.info(`Timed out after ${readinessTimeoutMs}ms of waiting for the page readiness. Continuing anyway`);
+        this.log.info(`Timed out after ${readinessTimeoutMs}ms of waiting for the page readiness. Continuing anyway`);
         isPageLoading = false;
         return;
       }
@@ -137,21 +136,21 @@ async function waitForDom (startPageLoadTimer) {
  * @param {number} [timeoutMs]
  * @returns {Promise<boolean>}
  */
-async function checkPageIsReady (timeoutMs) {
+export async function checkPageIsReady (timeoutMs) {
   checkParams({appIdKey: this.appIdKey});
 
   const readyCmd = 'document.readyState;';
   try {
     const readyState = await B.resolve(this.execute(readyCmd, true))
       .timeout(timeoutMs ?? this.pageReadyTimeout);
-    log.debug(`Document readyState is '${readyState}'. ` +
+    this.log.debug(`Document readyState is '${readyState}'. ` +
       `The pageLoadStrategy is '${this.pageLoadStrategy || PAGE_LOAD_STRATEGY.NORMAL}'`);
     return this.isPageLoadingCompleted(readyState);
   } catch (err) {
     if (!(err instanceof B.TimeoutError)) {
       throw err;
     }
-    log.debug(`Page readiness check timed out after ${this.pageReadyTimeout}ms`);
+    this.log.debug(`Page readiness check timed out after ${this.pageReadyTimeout}ms`);
     return false;
   }
 }
@@ -161,11 +160,10 @@ async function checkPageIsReady (timeoutMs) {
  * @param {string} url
  * @returns {Promise<void>}
  */
-async function navToUrl (url) {
+export async function navToUrl (url) {
   checkParams({appIdKey: this.appIdKey, pageIdKey: this.pageIdKey});
-  if (!this.rpcClient) {
-    throw new Error('rpcClient is undefined. Is the debugger connected?');
-  }
+  const rpcClient = this.requireRpcClient();
+
   try {
     new URL(url);
   } catch (e) {
@@ -173,7 +171,7 @@ async function navToUrl (url) {
   }
 
   this._navigatingToPage = true;
-  log.debug(`Navigating to new URL: '${url}'`);
+  this.log.debug(`Navigating to new URL: '${url}'`);
   const readinessTimeoutMs = this.pageLoadMs || DEFAULT_PAGE_READINESS_TIMEOUT_MS;
   /** @type {(() => void)|undefined} */
   let onPageLoaded;
@@ -192,7 +190,7 @@ async function navToUrl (url) {
     onPageLoadedTimeout = setTimeout(() => {
       if (isPageLoading) {
         isPageLoading = false;
-        log.info(
+        this.log.info(
           `Timed out after ${start.getDuration().asMilliSeconds.toFixed(0)}ms of waiting ` +
           `for the ${url} page readiness. Continuing anyway`
         );
@@ -203,7 +201,7 @@ async function navToUrl (url) {
     onPageLoaded = () => {
       if (isPageLoading) {
         isPageLoading = false;
-        log.debug(`The page ${url} is ready in ${start.getDuration().asMilliSeconds.toFixed(0)}ms`);
+        this.log.debug(`The page ${url} is ready in ${start.getDuration().asMilliSeconds.toFixed(0)}ms`);
       }
       if (onPageLoadedTimeout) {
         clearTimeout(onPageLoadedTimeout);
@@ -213,7 +211,7 @@ async function navToUrl (url) {
       return resolve();
     };
     // https://chromedevtools.github.io/devtools-protocol/tot/Page/#event-loadEventFired
-    this.rpcClient?.once('Page.loadEventFired', onPageLoaded);
+    rpcClient.once('Page.loadEventFired', onPageLoaded);
     // Pages that have no proper DOM structure do not fire the `Page.loadEventFired` event
     // so we rely on the very first event after target change, which is `onTargetProvisioned`
     // and start sending `document.readyState` requests until we either succeed or
@@ -233,9 +231,9 @@ async function navToUrl (url) {
         }
       }
     };
-    this.rpcClient?.targetSubscriptions.once(rpcConstants.ON_TARGET_PROVISIONED_EVENT, onTargetProvisioned);
+    rpcClient.targetSubscriptions.once(rpcConstants.ON_TARGET_PROVISIONED_EVENT, onTargetProvisioned);
 
-    this.rpcClient?.send('Page.navigate', {
+    rpcClient.send('Page.navigate', {
       url,
       appIdKey: this.appIdKey,
       pageIdKey: this.pageIdKey,
@@ -260,17 +258,17 @@ async function navToUrl (url) {
       onPageLoadedTimeout = null;
     }
     if (onTargetProvisioned) {
-      this.rpcClient.targetSubscriptions.off(rpcConstants.ON_TARGET_PROVISIONED_EVENT, onTargetProvisioned);
+      rpcClient.targetSubscriptions.off(rpcConstants.ON_TARGET_PROVISIONED_EVENT, onTargetProvisioned);
     }
     if (onPageLoaded) {
-      this.rpcClient.off('Page.loadEventFired', onPageLoaded);
+      rpcClient.off('Page.loadEventFired', onPageLoaded);
     }
   }
 
   // enable console logging, so we get the events (otherwise we only
   // get notified when navigating to a local page
   try {
-    await B.resolve(this.rpcClient.send('Console.enable', {
+    await B.resolve(rpcClient.send('Console.enable', {
       appIdKey: this.appIdKey,
       pageIdKey: this.pageIdKey,
     }, didPageFinishLoad)).timeout(CONSOLE_ENABLEMENT_TIMEOUT_MS);
@@ -282,5 +280,3 @@ async function navToUrl (url) {
     throw err;
   }
 }
-
-export default {frameDetached, cancelPageLoad, waitForDom, checkPageIsReady, navToUrl, isPageLoadingCompleted};

package/lib/mixins/screenshot.js

@@ -0,0 +1,34 @@
+/**
+ * Capture a rect of the page or by default the viewport
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {ScreenshotCaptureOptions} [opts={}]  if rect is null capture the whole
+ * coordinate system else capture the rect in the given coordinateSystem
+ * @returns {Promise<string>} a base64 encoded string of the screenshot
+ */
+export async function captureScreenshot(opts = {}) {
+  const {rect = null, coordinateSystem = 'Viewport'} = opts;
+  this.log.debug('Capturing screenshot');
+
+  const arect = rect ?? /** @type {import('@appium/types').Rect} */ (await this.executeAtom(
+    'execute_script',
+    ['return {x: 0, y: 0, width: window.innerWidth, height: window.innerHeight}', []]
+  ));
+  const response = await this.requireRpcClient().send('Page.snapshotRect', {
+    ...arect,
+    appIdKey: this.appIdKey,
+    pageIdKey: this.pageIdKey,
+    coordinateSystem,
+  });
+
+  if (response.error) {
+    throw new Error(response.error);
+  }
+
+  return response.dataURL.replace(/^data:image\/png;base64,/, '');
+}
+
+/**
+ * @typedef {Object} ScreenshotCaptureOptions
+ * @property {import('@appium/types').Rect | null} [rect=null]
+ * @property {"Viewport" | "Page"} [coordinateSystem="Viewport"]
+ */

package/lib/remote-debugger-real-device.js

@@ -1,9 +1,19 @@
 import RemoteDebugger from './remote-debugger';
 import { RpcClientRealDevice } from './rpc';
 
+/**
+ * @typedef {Object} RemoteDebuggerRealDeviceOptions
+ * @property {string} udid Real device UDID
+ */
 
 export default class RemoteDebuggerRealDevice extends RemoteDebugger {
-  constructor (opts = {}) {
+  /** @type {string} */
+  udid;
+
+  /**
+   * @param {RemoteDebuggerRealDeviceOptions & import('./remote-debugger').RemoteDebuggerOptions} opts
+   */
+  constructor (opts) {
     super(opts);
 
     this.udid = opts.udid;
@@ -11,6 +21,9 @@ export default class RemoteDebuggerRealDevice extends RemoteDebugger {
     this._skippedApps = ['lockdownd'];
   }
 
+  /**
+   * @override
+   */
   initRpcClient () {
     this.rpcClient = new RpcClientRealDevice({
       bundleId: this.bundleId,