How to use this.chromedriver.jwproxy.command method in Appium Android Driver

1import _ from 'lodash';2import Chromedriver from 'appium-chromedriver';3import PortFinder from 'portfinder';4import B from 'bluebird';5import { util } from '@appium/support';6import { errors } from '@appium/base-driver';7import {8  default as webviewHelpers,9  NATIVE_WIN, WEBVIEW_BASE, WEBVIEW_WIN, CHROMIUM_WIN, KNOWN_CHROME_PACKAGE_NAMES10} from '../webview-helpers';11import { APP_STATE } from '../android-helpers';12const CHROMEDRIVER_AUTODOWNLOAD_FEATURE = 'chromedriver_autodownload';13let commands = {}, helpers = {}, extensions = {};14/* -------------------------------15 * Actual MJSONWP command handlers16 * ------------------------------- */17commands.getCurrentContext = async function getCurrentContext () { // eslint-disable-line require-await18  // if the current context is `null`, indicating no context19  // explicitly set, it is the default context20  return this.curContext || this.defaultContextName();21};22commands.getContexts = async function getContexts () {23  const webviewsMapping = await webviewHelpers.getWebViewsMapping(this.adb, this.opts);24  return this.assignContexts(webviewsMapping);25};26commands.setContext = async function setContext (name) {27  if (!util.hasValue(name)) {28    name = this.defaultContextName();29  } else if (name === WEBVIEW_WIN) {30    // handle setContext "WEBVIEW"31    name = this.defaultWebviewName();32  }33  // if we're already in the context we want, do nothing34  if (name === this.curContext) {35    return;36  }37  const webviewsMapping = await webviewHelpers.getWebViewsMapping(this.adb, this.opts);38  const contexts = this.assignContexts(webviewsMapping);39  // if the context we want doesn't exist, fail40  if (!_.includes(contexts, name)) {41    throw new errors.NoSuchContextError();42  }43  await this.switchContext(name, webviewsMapping);44  this.curContext = name;45};46/**47 * @typedef {Object} WebviewsMapping48 * @property {string} proc The name of the Devtools Unix socket49 * @property {string} webview The web view alias. Looks like `WEBVIEW_`50 * prefix plus PID or package name51 * @property {?Object} info Webview information as it is retrieved by52 * /json/version CDP endpoint53 * @property {?Array<Object>} pages Webview pages list as it is retrieved by54 * /json/list CDP endpoint55 * @propery {?string} webviewName An actual webview name for switching context.56 * This value becomes null when failing to find a PID for a webview.57 *58 * The following json demonstrates the example of WebviewsMapping object.59 * Note that `description` in `page` can be an empty string most likely when it comes to Mobile Chrome)60 * {61 *   "proc": "@webview_devtools_remote_22138",62 *   "webview": "WEBVIEW_22138",63 *   "info": {64 *     "Android-Package": "io.appium.settings",65 *     "Browser": "Chrome/74.0.3729.185",66 *     "Protocol-Version": "1.3",67 *     "User-Agent": "Mozilla/5.0 (Linux; Android 10; Android SDK built for x86 Build/QSR1.190920.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/74.0.3729.185 Mobile Safari/537.36",68 *     "V8-Version": "7.4.288.28",69 *     "WebKit-Version": "537.36 (@22955682f94ce09336197bfb8dffea991fa32f0d)",70 *     "webSocketDebuggerUrl": "ws://127.0.0.1:10900/devtools/browser"71 *   },72 *   "pages": [73 *     {74 *       "description": "{\"attached\":true,\"empty\":false,\"height\":1458,\"screenX\":0,\"screenY\":336,\"visible\":true,\"width\":1080}",75 *       "devtoolsFrontendUrl": "http://chrome-devtools-frontend.appspot.com/serve_rev/@22955682f94ce09336197bfb8dffea991fa32f0d/inspector.html?ws=127.0.0.1:10900/devtools/page/27325CC50B600D31B233F45E09487B1F",76 *       "id": "27325CC50B600D31B233F45E09487B1F",77 *       "title": "Releases · appium/appium · GitHub",78 *       "type": "page",79 *       "url": "https://github.com/appium/appium/releases",80 *       "webSocketDebuggerUrl": "ws://127.0.0.1:10900/devtools/page/27325CC50B600D31B233F45E09487B1F"81 *     }82 *   ],83 *   "webviewName": "WEBVIEW_com.io.appium.setting"84 * }85 */86/**87 * Returns a webviewsMapping based on CDP endpoints88 *89 * @return {Array<WebviewsMapping>} webviewsMapping90 */91commands.mobileGetContexts = async function mobileGetContexts () {92  const opts = {93    androidDeviceSocket: this.opts.androidDeviceSocket,94    ensureWebviewsHavePages: true,95    webviewDevtoolsPort: this.opts.webviewDevtoolsPort,96    enableWebviewDetailsCollection: true97  };98  return await webviewHelpers.getWebViewsMapping(this.adb, opts);99};100helpers.assignContexts = function assignContexts (webviewsMapping) {101  const opts = Object.assign({isChromeSession: this.isChromeSession}, this.opts);102  const webviews = webviewHelpers.parseWebviewNames(webviewsMapping, opts);103  this.contexts = [NATIVE_WIN, ...webviews];104  this.log.debug(`Available contexts: ${JSON.stringify(this.contexts)}`);105  return this.contexts;106};107helpers.switchContext = async function switchContext (name, webviewsMapping) {108  // We have some options when it comes to webviews. If we want a109  // Chromedriver webview, we can only control one at a time.110  if (this.isChromedriverContext(name)) {111    // start proxying commands directly to chromedriver112    await this.startChromedriverProxy(name, webviewsMapping);113  } else if (this.isChromedriverContext(this.curContext)) {114    // if we're moving to a non-chromedriver webview, and our current context115    // _is_ a chromedriver webview, if caps recreateChromeDriverSessions is set116    // to true then kill chromedriver session using stopChromedriverProxies or117    // else simply suspend proxying to the latter118    if (this.opts.recreateChromeDriverSessions) {119      this.log.debug('recreateChromeDriverSessions set to true; killing existing chromedrivers');120      await this.stopChromedriverProxies();121    } else {122      await this.suspendChromedriverProxy();123    }124  } else {125    throw new Error(`Didn't know how to handle switching to context '${name}'`);126  }127};128/* ---------------------------------129 * On-object context-related helpers130 * --------------------------------- */131// The reason this is a function and not just a constant is that both android-132// driver and selendroid-driver use this logic, and each one returns133// a different default context name134helpers.defaultContextName = function defaultContextName () {135  return NATIVE_WIN;136};137helpers.defaultWebviewName = function defaultWebviewName () {138  return WEBVIEW_BASE + this.opts.appPackage;139};140helpers.isWebContext = function isWebContext () {141  return this.curContext !== null && this.curContext !== NATIVE_WIN;142};143// Turn on proxying to an existing Chromedriver session or a new one144helpers.startChromedriverProxy = async function startChromedriverProxy (context, webviewsMapping) {145  this.log.debug(`Connecting to chrome-backed webview context '${context}'`);146  let cd;147  if (this.sessionChromedrivers[context]) {148    // in the case where we've already set up a chromedriver for a context,149    // we want to reconnect to it, not create a whole new one150    this.log.debug(`Found existing Chromedriver for context '${context}'. Using it.`);151    cd = this.sessionChromedrivers[context];152    await setupExistingChromedriver(this.log, cd);153  } else {154    let opts = _.cloneDeep(this.opts);155    opts.chromeUseRunningApp = true;156    // if requested, tell chromedriver to attach to the android package we have157    // associated with the context name, rather than the package of the AUT.158    // And turn this on by default for chrome--if chrome pops up with a webview159    // and someone wants to switch to it, we should let chromedriver connect to160    // chrome rather than staying stuck on the AUT161    if (opts.extractChromeAndroidPackageFromContextName || context === `${WEBVIEW_BASE}chrome`) {162      let androidPackage = context.match(`${WEBVIEW_BASE}(.+)`);163      if (androidPackage && androidPackage.length > 0) {164        opts.chromeAndroidPackage = androidPackage[1];165      }166      if (!opts.extractChromeAndroidPackageFromContextName) {167        if (_.has(this.opts, 'enableWebviewDetailsCollection') && !this.opts.enableWebviewDetailsCollection) {168          // When enableWebviewDetailsCollection capability is explicitly disabled, try to identify169          // chromeAndroidPackage based on contexts, known chrome variant packages and queryAppState result170          // since webviewsMapping does not have info object171          const contexts = webviewsMapping.map((wm) => wm.webviewName);172          for (const knownPackage of KNOWN_CHROME_PACKAGE_NAMES) {173            if (_.includes(contexts, `${WEBVIEW_BASE}${knownPackage}`)) {174              continue;175            }176            const appState = await this.queryAppState(knownPackage);177            if (_.includes([APP_STATE.RUNNING_IN_BACKGROUND, APP_STATE.RUNNING_IN_FOREGROUND], appState)) {178              opts.chromeAndroidPackage = knownPackage;179              this.log.debug(`Identified chromeAndroidPackage as '${opts.chromeAndroidPackage}' ` +180                `for context '${context}' by querying states of Chrome app packages`);181              break;182            }183          }184        } else {185          for (const wm of webviewsMapping) {186            if (wm.webviewName === context && _.has(wm?.info, 'Android-Package')) {187              opts.chromeAndroidPackage = wm.info['Android-Package'];188              this.log.debug(`Identified chromeAndroidPackage as '${opts.chromeAndroidPackage}' ` +189                `for context '${context}' by CDP`);190              break;191            }192          }193        }194      }195    }196    cd = await this.setupNewChromedriver(opts, this.adb.curDeviceId, this.adb, context);197    // bind our stop/exit handler, passing in context so we know which198    // one stopped unexpectedly199    cd.on(Chromedriver.EVENT_CHANGED, (msg) => {200      if (msg.state === Chromedriver.STATE_STOPPED) {201        this.onChromedriverStop(context);202      }203    });204    // save the chromedriver object under the context205    this.sessionChromedrivers[context] = cd;206  }207  // hook up the local variables so we can proxy this biz208  this.chromedriver = cd;209  this.proxyReqRes = this.chromedriver.proxyReq.bind(this.chromedriver);210  this.proxyCommand = this.chromedriver.jwproxy.command.bind(this.chromedriver.jwproxy);211  this.jwpProxyActive = true;212};213// Stop proxying to any Chromedriver214helpers.suspendChromedriverProxy = function suspendChromedriverProxy () {215  this.chromedriver = null;216  this.proxyReqRes = null;217  this.proxyCommand = null;218  this.jwpProxyActive = false;219};220// Handle an out-of-band Chromedriver stop event221helpers.onChromedriverStop = async function onChromedriverStop (context) {222  this.log.warn(`Chromedriver for context ${context} stopped unexpectedly`);223  if (context === this.curContext) {224    // we exited unexpectedly while automating the current context and so want225    // to shut down the session and respond with an error226    let err = new Error('Chromedriver quit unexpectedly during session');227    await this.startUnexpectedShutdown(err);228  } else {229    // if a Chromedriver in the non-active context barfs, we don't really230    // care, we'll just make a new one next time we need the context.231    this.log.warn("Chromedriver quit unexpectedly, but it wasn't the active " +232      'context, ignoring');233    delete this.sessionChromedrivers[context];234  }235};236// Intentionally stop all the chromedrivers currently active, and ignore237// their exit events238helpers.stopChromedriverProxies = async function stopChromedriverProxies () {239  this.suspendChromedriverProxy(); // make sure we turn off the proxy flag240  for (let context of _.keys(this.sessionChromedrivers)) {241    let cd = this.sessionChromedrivers[context];242    this.log.debug(`Stopping chromedriver for context ${context}`);243    // stop listening for the stopped state event244    cd.removeAllListeners(Chromedriver.EVENT_CHANGED);245    try {246      await cd.stop();247    } catch (err) {248      this.log.warn(`Error stopping Chromedriver: ${err.message}`);249    }250    delete this.sessionChromedrivers[context];251  }252};253helpers.isChromedriverContext = function isChromedriverContext (viewName) {254  return _.includes(viewName, WEBVIEW_WIN) || viewName === CHROMIUM_WIN;255};256helpers.shouldDismissChromeWelcome = function shouldDismissChromeWelcome () {257  return !!this.opts.chromeOptions &&258         _.isArray(this.opts.chromeOptions.args) &&259         this.opts.chromeOptions.args.includes('--no-first-run');260};261helpers.dismissChromeWelcome = async function dismissChromeWelcome () {262  this.log.info('Trying to dismiss Chrome welcome');263  let activity = await this.getCurrentActivity();264  if (activity !== 'org.chromium.chrome.browser.firstrun.FirstRunActivity') {265    this.log.info('Chrome welcome dialog never showed up! Continuing');266    return;267  }268  let el = await this.findElOrEls('id', 'com.android.chrome:id/terms_accept', false);269  await this.click(el.ELEMENT);270  try {271    let el = await this.findElOrEls('id', 'com.android.chrome:id/negative_button', false);272    await this.click(el.ELEMENT);273  } catch (e) {274    // DO NOTHING, THIS DEVICE DIDNT LAUNCH THE SIGNIN DIALOG275    // IT MUST BE A NON GMS DEVICE276    this.log.warn(`This device did not show Chrome SignIn dialog, ${e.message}`);277  }278};279helpers.startChromeSession = async function startChromeSession () {280  this.log.info('Starting a chrome-based browser session');281  let opts = _.cloneDeep(this.opts);282  const knownPackages = [283    'org.chromium.chrome.shell',284    'com.android.chrome',285    'com.chrome.beta',286    'org.chromium.chrome',287    'org.chromium.webview_shell',288  ];289  if (_.includes(knownPackages, this.opts.appPackage)) {290    opts.chromeBundleId = this.opts.appPackage;291  } else {292    opts.chromeAndroidActivity = this.opts.appActivity;293  }294  this.chromedriver = await this.setupNewChromedriver(opts, this.adb.curDeviceId, this.adb);295  this.chromedriver.on(Chromedriver.EVENT_CHANGED, (msg) => {296    if (msg.state === Chromedriver.STATE_STOPPED) {297      this.onChromedriverStop(CHROMIUM_WIN);298    }299  });300  // Now that we have a Chrome session, we ensure that the context is301  // appropriately set and that this chromedriver is added to the list302  // of session chromedrivers so we can switch back and forth303  this.curContext = CHROMIUM_WIN;304  this.sessionChromedrivers[CHROMIUM_WIN] = this.chromedriver;305  this.proxyReqRes = this.chromedriver.proxyReq.bind(this.chromedriver);306  this.proxyCommand = this.chromedriver.jwproxy.command.bind(this.chromedriver.jwproxy);307  this.jwpProxyActive = true;308  if (this.shouldDismissChromeWelcome()) {309    // dismiss Chrome welcome dialog310    await this.dismissChromeWelcome();311  }312};313/* --------------------------314 * Internal library functions315 * -------------------------- */316async function setupExistingChromedriver (log, chromedriver) {317  // check the status by sending a simple window-based command to ChromeDriver318  // if there is an error, we want to recreate the ChromeDriver session319  if (!await chromedriver.hasWorkingWebview()) {320    log.debug('ChromeDriver is not associated with a window. ' +321                 'Re-initializing the session.');322    await chromedriver.restart();323  }324  return chromedriver;325}326/**327 * Find a free port to have Chromedriver listen on.328 *329 * @param {array} portSpec - Array which is a list of ports. A list item may330 * also itself be an array of length 2 specifying a start and end port of331 * a range. Some valid port specs:332 *    - [8000, 8001, 8002]333 *    - [[8000, 8005]]334 *    - [8000, [9000, 9100]]335 * @param {Object?} log Logger instance336 *337 * @return {number} A free port338 */339async function getChromedriverPort (portSpec, log = null) {340  const getPort = B.promisify(PortFinder.getPort, {context: PortFinder});341  // if the user didn't give us any specific information about chromedriver342  // port ranges, just find any free port343  if (!portSpec) {344    const port = await getPort();345    log?.debug(`A port was not given, using random free port: ${port}`);346    return port;347  }348  // otherwise find the free port based on a list or range provided by the user349  log?.debug(`Finding a free port for chromedriver using spec ${JSON.stringify(portSpec)}`);350  let foundPort = null;351  for (const potentialPort of portSpec) {352    let port, stopPort;353    if (_.isArray(potentialPort)) {354      ([port, stopPort] = potentialPort);355    } else {356      port = parseInt(potentialPort, 10); // ensure we have a number and not a string357      stopPort = port;358    }359    try {360      log?.debug(`Checking port range ${port}:${stopPort}`);361      foundPort = await getPort({port, stopPort});362      break;363    } catch (e) {364      log?.debug(`Nothing in port range ${port}:${stopPort} was available`);365    }366  }367  if (foundPort === null) {368    throw new Error(`Could not find a free port for chromedriver using ` +369                    `chromedriverPorts spec ${JSON.stringify(portSpec)}`);370  }371  log?.debug(`Using free port ${foundPort} for chromedriver`);372  return foundPort;373}374helpers.isChromedriverAutodownloadEnabled = function isChromedriverAutodownloadEnabled () {375  if (this.isFeatureEnabled(CHROMEDRIVER_AUTODOWNLOAD_FEATURE)) {376    return true;377  }378  this?.log?.debug(`Automated Chromedriver download is disabled. ` +379    `Use '${CHROMEDRIVER_AUTODOWNLOAD_FEATURE}' server feature to enable it`);380  return false;381};382helpers.setupNewChromedriver = async function setupNewChromedriver (opts, curDeviceId, adb, context = null) {383  if (opts.chromeDriverPort) {384    this?.log?.warn(`The 'chromeDriverPort' capability is deprecated. Please use 'chromedriverPort' instead`);385    opts.chromedriverPort = opts.chromeDriverPort;386  }387  if (opts.chromedriverPort) {388    this?.log?.debug(`Using user-specified port ${opts.chromedriverPort} for chromedriver`);389  } else {390    // if a single port wasn't given, we'll look for a free one391    opts.chromedriverPort = await getChromedriverPort(opts.chromedriverPorts, this?.log);392  }393  const details = context ? webviewHelpers.getWebviewDetails(adb, context) : undefined;394  if (!_.isEmpty(details)) {395    this?.log?.debug('Passing web view details to the Chromedriver constructor: ' +396      JSON.stringify(details, null, 2));397  }398  const chromedriver = new Chromedriver({399    port: opts.chromedriverPort,400    executable: opts.chromedriverExecutable,401    adb,402    cmdArgs: opts.chromedriverArgs,403    verbose: !!opts.showChromedriverLog,404    executableDir: opts.chromedriverExecutableDir,405    mappingPath: opts.chromedriverChromeMappingFile,406    bundleId: opts.chromeBundleId,407    useSystemExecutable: opts.chromedriverUseSystemExecutable,408    disableBuildCheck: opts.chromedriverDisableBuildCheck,409    details,410    isAutodownloadEnabled: this?.isChromedriverAutodownloadEnabled?.()411  });412  // make sure there are chromeOptions413  opts.chromeOptions = opts.chromeOptions || {};414  // try out any prefixed chromeOptions,415  // and strip the prefix416  for (const opt of _.keys(opts)) {417    if (opt.endsWith(':chromeOptions')) {418      this?.log?.warn(`Merging '${opt}' into 'chromeOptions'. This may cause unexpected behavior`);419      _.merge(opts.chromeOptions, opts[opt]);420    }421  }422  const caps = webviewHelpers.createChromedriverCaps(opts, curDeviceId, details);423  this?.log?.debug(`Before starting chromedriver, androidPackage is '${caps.chromeOptions.androidPackage}'`);424  await chromedriver.start(caps);425  return chromedriver;426};427const setupNewChromedriver = helpers.setupNewChromedriver;428Object.assign(extensions, commands, helpers);429export { commands, helpers, setupNewChromedriver };...

...110};111commands.getLogTypes = async function getLogTypes () {112  const nativeLogTypes = await BaseDriver.prototype.getLogTypes.call(this);113  if (this.isWebContext()) {114    const webLogTypes = await this.chromedriver.jwproxy.command('/log/types', 'GET');115    return [...nativeLogTypes, ...webLogTypes];116  }117  return nativeLogTypes;118};119commands.getLog = async function getLog (logType) {120  if (this.isWebContext() && !_.keys(this.supportedLogTypes).includes(logType)) {121    return await this.chromedriver.jwproxy.command('/log', 'POST', {type: logType});122  }123  return await BaseDriver.prototype.getLog.call(this, logType);124};125Object.assign(extensions, commands, helpers);126export { commands, helpers };...

...85commands.getElementRect = async function (elementId) {86  if (this.isWebContext()) {87    log.debug(`Detected downstream chromedriver protocol: ${this.chromedriver.jwproxy.downstreamProtocol}`);88    if (this.chromedriver.jwproxy.downstreamProtocol === PROTOCOLS.MJSONWP) {89      const {x, y} = await this.chromedriver.jwproxy.command(`/element/${elementId}/location`, 'GET');90      const {width, height} = await this.chromedriver.jwproxy.command(`/element/${elementId}/size`, 'GET');91      return {x, y, width, height};92    }93    return await this.chromedriver.jwproxy.command(`/element/${elementId}/rect`, 'GET');94  }95  return await this.uiautomator2.jwproxy.command(`/element/${elementId}/rect`, 'GET');96};97Object.assign(extensions, commands, helpers);98export { commands, helpers };...

...13  }14  const endpoint = this.chromedriver.jwproxy.downstreamProtocol === PROTOCOLS.MJSONWP15    ? '/execute'16    : '/execute/sync';17  return await this.chromedriver.jwproxy.command(endpoint, 'POST', {18    script,19    args,20  });21};22extensions.executeMobile = async function executeMobile (mobileCommand, opts = {}) {23  const mobileCommandsMapping = {24    pressButton: 'mobilePressButton',25    shell: 'mobileShell',26  };27  if (!_.has(mobileCommandsMapping, mobileCommand)) {28    throw new errors.UnknownCommandError(`Unknown mobile command "${mobileCommand}". ` +29      `Only ${_.keys(mobileCommandsMapping)} commands are supported.`);30  }31  const command = mobileCommandsMapping[mobileCommand];...