appium-android-driver 7.8.2 → 8.0.0

package/lib/commands/recordscreen.js

@@ -1,11 +1,8 @@
-// @ts-check
-
 import {fs, net, system, tempDir, timing, util} from '@appium/support';
 import {waitForCondition} from 'asyncbox';
 import _ from 'lodash';
 import path from 'path';
 import {exec} from 'teen_process';
-import {mixin} from './mixins';
 
 const RETRY_PAUSE = 300;
 const RETRY_TIMEOUT = 5000;
@@ -18,6 +15,155 @@ const DEFAULT_EXT = '.mp4';
 const MIN_EMULATOR_API_LEVEL = 27;
 const FFMPEG_BINARY = `ffmpeg${system.isWindows() ? '.exe' : ''}`;
 
+/**
+ *
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').StartScreenRecordingOpts} [options={}]
+ * @returns {Promise<string>}
+ */
+export async function startRecordingScreen(options = {}) {
+  await verifyScreenRecordIsSupported(this.adb, this.isEmulator());
+
+  let result = '';
+  const {
+    videoSize,
+    timeLimit = DEFAULT_RECORDING_TIME_SEC,
+    bugReport,
+    bitRate,
+    forceRestart,
+  } = options;
+  if (!forceRestart) {
+    result = await this.stopRecordingScreen(options);
+  }
+
+  if (await terminateBackgroundScreenRecording(this.adb, true)) {
+    this.log.warn(
+      `There were some ${SCREENRECORD_BINARY} process leftovers running ` +
+        `in the background. Make sure you stop screen recording each time after it is started, ` +
+        `otherwise the recorded media might quickly exceed all the free space on the device under test.`,
+    );
+  }
+
+  if (!_.isEmpty(this._screenRecordingProperties)) {
+    // XXX: this doesn't need to be done in serial, does it?
+    for (const record of this._screenRecordingProperties.records || []) {
+      await this.adb.rimraf(record);
+    }
+    this._screenRecordingProperties = undefined;
+  }
+
+  const timeout = parseFloat(String(timeLimit));
+  if (isNaN(timeout) || timeout > MAX_TIME_SEC || timeout <= 0) {
+    throw new Error(
+      `The timeLimit value must be in range [1, ${MAX_TIME_SEC}] seconds. ` +
+        `The value of '${timeLimit}' has been passed instead.`,
+    );
+  }
+
+  this._screenRecordingProperties = {
+    timer: new timing.Timer().start(),
+    videoSize,
+    timeLimit,
+    currentTimeLimit: timeLimit,
+    bitRate,
+    bugReport,
+    records: [],
+    recordingProcess: null,
+    stopped: false,
+  };
+  await scheduleScreenRecord.bind(this)(this._screenRecordingProperties);
+  return result;
+}
+
+/**
+ *
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').StopScreenRecordingOpts} [options={}]
+ * @returns {Promise<string>}
+ */
+export async function stopRecordingScreen(options = {}) {
+  await verifyScreenRecordIsSupported(this.adb, this.isEmulator());
+
+  if (!_.isEmpty(this._screenRecordingProperties)) {
+    this._screenRecordingProperties.stopped = true;
+  }
+
+  try {
+    await terminateBackgroundScreenRecording(this.adb, false);
+  } catch (err) {
+    this.log.warn(/** @type {Error} */ (err).message);
+    if (!_.isEmpty(this._screenRecordingProperties)) {
+      this.log.warn('The resulting video might be corrupted');
+    }
+  }
+
+  if (_.isEmpty(this._screenRecordingProperties)) {
+    this.log.info(
+      `Screen recording has not been previously started by Appium. There is nothing to stop`,
+    );
+    return '';
+  }
+
+  if (
+    this._screenRecordingProperties.recordingProcess &&
+    this._screenRecordingProperties.recordingProcess.isRunning
+  ) {
+    try {
+      await this._screenRecordingProperties.recordingProcess.stop(
+        'SIGINT',
+        PROCESS_SHUTDOWN_TIMEOUT,
+      );
+    } catch (e) {
+      this.log.errorAndThrow(
+        `Unable to stop screen recording within ${PROCESS_SHUTDOWN_TIMEOUT}ms`,
+      );
+    }
+    this._screenRecordingProperties.recordingProcess = null;
+  }
+
+  if (_.isEmpty(this._screenRecordingProperties.records)) {
+    this.log.errorAndThrow(
+      `No screen recordings have been stored on the device so far. ` +
+        `Are you sure the ${SCREENRECORD_BINARY} utility works as expected?`,
+    );
+  }
+
+  const tmpRoot = await tempDir.openDir();
+  try {
+    const localRecords = [];
+    for (const pathOnDevice of this._screenRecordingProperties.records) {
+      const relativePath = path.resolve(tmpRoot, path.posix.basename(pathOnDevice));
+      localRecords.push(relativePath);
+      await this.adb.pull(pathOnDevice, relativePath);
+      await this.adb.rimraf(pathOnDevice);
+    }
+    let resultFilePath = /** @type {string} */ (_.last(localRecords));
+    if (localRecords.length > 1) {
+      this.log.info(`Got ${localRecords.length} screen recordings. Trying to merge them`);
+      try {
+        resultFilePath = await mergeScreenRecords.bind(this)(localRecords);
+      } catch (e) {
+        this.log.warn(
+          `Cannot merge the recorded files. The most recent screen recording is going to be returned as the result. ` +
+            `Original error: ${/** @type {Error} */ (e).message}`,
+        );
+      }
+    }
+    if (_.isEmpty(options.remotePath)) {
+      const {size} = await fs.stat(resultFilePath);
+      this.log.debug(
+        `The size of the resulting screen recording is ${util.toReadableSizeString(size)}`,
+      );
+    }
+    return await uploadRecordedMedia(resultFilePath, options.remotePath, options);
+  } finally {
+    await fs.rimraf(tmpRoot);
+    this._screenRecordingProperties = undefined;
+  }
+}
+
+// #region Internal helpers
+
 /**
  *
  * @param {string} localFile
@@ -56,24 +202,22 @@ async function verifyScreenRecordIsSupported(adb, isEmulator) {
   const apiLevel = await adb.getApiLevel();
   if (isEmulator && apiLevel < MIN_EMULATOR_API_LEVEL) {
     throw new Error(
-      `Screen recording does not work on emulators running Android API level less than ${MIN_EMULATOR_API_LEVEL}`
+      `Screen recording does not work on emulators running Android API level less than ${MIN_EMULATOR_API_LEVEL}`,
     );
   }
   if (apiLevel < 19) {
     throw new Error(
-      `Screen recording not available on API Level ${apiLevel}. Minimum API Level is 19.`
+      `Screen recording not available on API Level ${apiLevel}. Minimum API Level is 19.`,
     );
   }
 }
 
 /**
- *
- * @param {ADB} adb
+ * @this {import('../driver').AndroidDriver}
  * @param {import('@appium/types').StringRecord} recordingProperties
- * @param {import('@appium/types').AppiumLogger} [log]
  * @returns {Promise<void>}
  */
-async function scheduleScreenRecord(adb, recordingProperties, log) {
+async function scheduleScreenRecord(recordingProperties) {
   if (recordingProperties.stopped) {
     return;
   }
@@ -88,7 +232,7 @@ async function scheduleScreenRecord(adb, recordingProperties, log) {
     }
   }
   const pathOnDevice = `/sdcard/${util.uuidV4().substring(0, 8)}${DEFAULT_EXT}`;
-  const recordingProc = adb.screenrecord(pathOnDevice, {
+  const recordingProc = this.adb.screenrecord(pathOnDevice, {
     videoSize,
     bitRate,
     timeLimit: currentTimeLimit,
@@ -100,10 +244,10 @@ async function scheduleScreenRecord(adb, recordingProperties, log) {
       return;
     }
     const currentDuration = timer.getDuration().asSeconds.toFixed(0);
-    log?.debug(`The overall screen recording duration is ${currentDuration}s so far`);
+    this.log.debug(`The overall screen recording duration is ${currentDuration}s so far`);
     const timeLimitInt = parseInt(timeLimit, 10);
     if (isNaN(timeLimitInt) || currentDuration >= timeLimitInt) {
-      log?.debug('There is no need to start the next recording chunk');
+      this.log.debug('There is no need to start the next recording chunk');
       return;
     }
 
@@ -112,15 +256,15 @@ async function scheduleScreenRecord(adb, recordingProperties, log) {
       recordingProperties.currentTimeLimit < MAX_RECORDING_TIME_SEC
         ? recordingProperties.currentTimeLimit
         : MAX_RECORDING_TIME_SEC;
-    log?.debug(
+    this.log.debug(
       `Starting the next ${chunkDuration}s-chunk ` +
-        `of screen recording in order to achieve ${timeLimitInt}s total duration`
+        `of screen recording in order to achieve ${timeLimitInt}s total duration`,
     );
     (async () => {
       try {
-        await scheduleScreenRecord(adb, recordingProperties, log);
+        await scheduleScreenRecord.bind(this)(recordingProperties);
       } catch (e) {
-        log?.error(/** @type {Error} */ (e).stack);
+        this.log.error(/** @type {Error} */ (e).stack);
         recordingProperties.stopped = true;
       }
     })();
@@ -128,14 +272,14 @@ async function scheduleScreenRecord(adb, recordingProperties, log) {
 
   await recordingProc.start(0);
   try {
-    await waitForCondition(async () => await adb.fileExists(pathOnDevice), {
+    await waitForCondition(async () => await this.adb.fileExists(pathOnDevice), {
       waitMs: RETRY_TIMEOUT,
       intervalMs: RETRY_PAUSE,
     });
   } catch (e) {
     throw new Error(
       `The expected screen record file '${pathOnDevice}' does not exist after ${RETRY_TIMEOUT}ms. ` +
-        `Is ${SCREENRECORD_BINARY} utility available and operational on the device under test?`
+        `Is ${SCREENRECORD_BINARY} utility available and operational on the device under test?`,
     );
   }
 
@@ -145,29 +289,29 @@ async function scheduleScreenRecord(adb, recordingProperties, log) {
 
 /**
  *
+ * @this {import('../driver').AndroidDriver}
  * @param {string[]} mediaFiles
- * @param {import('@appium/types').AppiumLogger} [log]
  * @returns {Promise<string>}
  */
-async function mergeScreenRecords(mediaFiles, log) {
+async function mergeScreenRecords(mediaFiles) {
   try {
     await fs.which(FFMPEG_BINARY);
   } catch (e) {
     throw new Error(
-      `${FFMPEG_BINARY} utility is not available in PATH. Please install it from https://www.ffmpeg.org/`
+      `${FFMPEG_BINARY} utility is not available in PATH. Please install it from https://www.ffmpeg.org/`,
     );
   }
   const configContent = mediaFiles.map((x) => `file '${x}'`).join('\n');
   const configFile = path.resolve(path.dirname(mediaFiles[0]), 'config.txt');
   await fs.writeFile(configFile, configContent, 'utf8');
-  log?.debug(`Generated ffmpeg merging config '${configFile}' with items:\n${configContent}`);
+  this.log.debug(`Generated ffmpeg merging config '${configFile}' with items:\n${configContent}`);
   const result = path.resolve(
     path.dirname(mediaFiles[0]),
-    `merge_${Math.floor(+new Date())}${DEFAULT_EXT}`
+    `merge_${Math.floor(+new Date())}${DEFAULT_EXT}`,
   );
   const args = ['-safe', '0', '-f', 'concat', '-i', configFile, '-c', 'copy', result];
-  log?.info(
-    `Initiating screen records merging using the command '${FFMPEG_BINARY} ${args.join(' ')}'`
+  this.log.info(
+    `Initiating screen records merging using the command '${FFMPEG_BINARY} ${args.join(' ')}'`,
   );
   await exec(FFMPEG_BINARY, args);
   return result;
@@ -194,155 +338,12 @@ async function terminateBackgroundScreenRecording(adb, force = true) {
     return true;
   } catch (err) {
     throw new Error(
-      `Unable to stop the background screen recording: ${/** @type {Error} */ (err).message}`
+      `Unable to stop the background screen recording: ${/** @type {Error} */ (err).message}`,
     );
   }
 }
 
-/**
- * @type {import('./mixins').RecordScreenMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
- */
-const RecordScreenMixin = {
-  async startRecordingScreen(options = {}) {
-    await verifyScreenRecordIsSupported(this.adb, this.isEmulator());
-
-    let result = '';
-    const {
-      videoSize,
-      timeLimit = DEFAULT_RECORDING_TIME_SEC,
-      bugReport,
-      bitRate,
-      forceRestart,
-    } = options;
-    if (!forceRestart) {
-      result = await this.stopRecordingScreen(options);
-    }
-
-    if (await terminateBackgroundScreenRecording(this.adb, true)) {
-      this.log.warn(
-        `There were some ${SCREENRECORD_BINARY} process leftovers running ` +
-          `in the background. Make sure you stop screen recording each time after it is started, ` +
-          `otherwise the recorded media might quickly exceed all the free space on the device under test.`
-      );
-    }
-
-    if (!_.isEmpty(this._screenRecordingProperties)) {
-      // XXX: this doesn't need to be done in serial, does it?
-      for (const record of this._screenRecordingProperties.records || []) {
-        await this.adb.rimraf(record);
-      }
-      this._screenRecordingProperties = undefined;
-    }
-
-    const timeout = parseFloat(String(timeLimit));
-    if (isNaN(timeout) || timeout > MAX_TIME_SEC || timeout <= 0) {
-      throw new Error(
-        `The timeLimit value must be in range [1, ${MAX_TIME_SEC}] seconds. ` +
-          `The value of '${timeLimit}' has been passed instead.`
-      );
-    }
-
-    this._screenRecordingProperties = {
-      timer: new timing.Timer().start(),
-      videoSize,
-      timeLimit,
-      currentTimeLimit: timeLimit,
-      bitRate,
-      bugReport,
-      records: [],
-      recordingProcess: null,
-      stopped: false,
-    };
-    await scheduleScreenRecord(this.adb, this._screenRecordingProperties, this.log);
-    return result;
-  },
-
-  async stopRecordingScreen(options = {}) {
-    await verifyScreenRecordIsSupported(this.adb, this.isEmulator());
-
-    if (!_.isEmpty(this._screenRecordingProperties)) {
-      this._screenRecordingProperties.stopped = true;
-    }
-
-    try {
-      await terminateBackgroundScreenRecording(this.adb, false);
-    } catch (err) {
-      this.log.warn(/** @type {Error} */ (err).message);
-      if (!_.isEmpty(this._screenRecordingProperties)) {
-        this.log.warn('The resulting video might be corrupted');
-      }
-    }
-
-    if (_.isEmpty(this._screenRecordingProperties)) {
-      this.log.info(
-        `Screen recording has not been previously started by Appium. There is nothing to stop`
-      );
-      return '';
-    }
-
-    if (
-      this._screenRecordingProperties.recordingProcess &&
-      this._screenRecordingProperties.recordingProcess.isRunning
-    ) {
-      try {
-        await this._screenRecordingProperties.recordingProcess.stop(
-          'SIGINT',
-          PROCESS_SHUTDOWN_TIMEOUT
-        );
-      } catch (e) {
-        this.log.errorAndThrow(
-          `Unable to stop screen recording within ${PROCESS_SHUTDOWN_TIMEOUT}ms`
-        );
-      }
-      this._screenRecordingProperties.recordingProcess = null;
-    }
-
-    if (_.isEmpty(this._screenRecordingProperties.records)) {
-      this.log.errorAndThrow(
-        `No screen recordings have been stored on the device so far. ` +
-          `Are you sure the ${SCREENRECORD_BINARY} utility works as expected?`
-      );
-    }
-
-    const tmpRoot = await tempDir.openDir();
-    try {
-      const localRecords = [];
-      for (const pathOnDevice of this._screenRecordingProperties.records) {
-        const relativePath = path.resolve(tmpRoot, path.posix.basename(pathOnDevice));
-        localRecords.push(relativePath);
-        await this.adb.pull(pathOnDevice, relativePath);
-        await this.adb.rimraf(pathOnDevice);
-      }
-      let resultFilePath = /** @type {string} */ (_.last(localRecords));
-      if (localRecords.length > 1) {
-        this.log.info(`Got ${localRecords.length} screen recordings. Trying to merge them`);
-        try {
-          resultFilePath = await mergeScreenRecords(localRecords, this.log);
-        } catch (e) {
-          this.log.warn(
-            `Cannot merge the recorded files. The most recent screen recording is going to be returned as the result. ` +
-              `Original error: ${/** @type {Error} */ (e).message}`
-          );
-        }
-      }
-      if (_.isEmpty(options.remotePath)) {
-        const {size} = await fs.stat(resultFilePath);
-        this.log.debug(
-          `The size of the resulting screen recording is ${util.toReadableSizeString(size)}`
-        );
-      }
-      return await uploadRecordedMedia(resultFilePath, options.remotePath, options);
-    } finally {
-      await fs.rimraf(tmpRoot);
-      this._screenRecordingProperties = undefined;
-    }
-  },
-};
-
-mixin(RecordScreenMixin);
-
-export default RecordScreenMixin;
+// #endregion
 
 /**
  * @typedef {import('appium-adb').ADB} ADB

package/lib/commands/resources.js

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import _ from 'lodash';
+import {fs, util} from '@appium/support';
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string?} [language=null]
+ * @returns {Promise<import('@appium/types').StringRecord>}}
+ */
+export async function getStrings(language = null) {
+  if (!language) {
+    language = await this.adb.getDeviceLanguage();
+    this.log.info(`No language specified, returning strings for: ${language}`);
+  }
+
+  // Clients require the resulting mapping to have both keys
+  // and values of type string
+  /** @param {import('@appium/types').StringRecord} mapping */
+  const preprocessStringsMap = (mapping) => {
+    /** @type {import('@appium/types').StringRecord} */
+    const result = {};
+    for (const [key, value] of _.toPairs(mapping)) {
+      result[key] = _.isString(value) ? value : JSON.stringify(value);
+    }
+    return result;
+  };
+
+  if (!this.apkStrings[language]) {
+    this.apkStrings[language] = await extractStringsFromResources.bind(this)(language);
+  }
+  const mapping = JSON.parse(await fs.readFile(this.apkStrings[language], 'utf-8'));
+  return preprocessStringsMap(mapping);
+}
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string} language
+ * @param {string} country
+ * @param {string} [script]
+ * @returns {Promise<void>}}
+ */
+export async function ensureDeviceLocale(language, country, script) {
+  await this.settingsApp.setDeviceLocale(language, country, script);
+
+  if (!(await this.adb.ensureCurrentLocale(language, country, script))) {
+    const message = script
+      ? `language: ${language}, country: ${country} and script: ${script}`
+      : `language: ${language} and country: ${country}`;
+    throw new Error(`Failed to set ${message}`);
+  }
+}
+
+// #region Internal helpers
+
+/**
+ * @this {import('../driver').AndroidDriver}
+ * @param {string?} [language]
+ * @param {import('../driver').AndroidDriverOpts?} [opts=null]
+ * @returns {Promise<string>};
+ */
+async function extractStringsFromResources(language, opts = null) {
+  const caps = opts ?? this.opts;
+
+  /** @type {string|undefined} */
+  let app;
+  try {
+    app =
+      caps.app ||
+      (caps.appPackage && caps.tmpDir && (await this.adb.pullApk(caps.appPackage, caps.tmpDir)));
+  } catch (err) {
+    throw new Error(
+      `Failed to pull an apk from '${caps.appPackage}' to '${caps.tmpDir}'. Original error: ${err.message}`,
+    );
+  }
+
+  if (!app || !(await fs.exists(app))) {
+    throw new Error(`Could not extract app strings, no app or package specified`);
+  }
+
+  const stringsTmpDir = path.resolve(String(caps.tmpDir), util.uuidV4());
+  try {
+    this.log.debug(
+      `Extracting strings from '${app}' for the language '${language || 'default'}' into '${stringsTmpDir}'`,
+    );
+    const {localPath} = await this.adb.extractStringsFromApk(app, language ?? null, stringsTmpDir);
+    return localPath;
+  } catch (err) {
+    throw new Error(`Could not extract app strings. Original error: ${err.message}`);
+  }
+}
+
+// #endregion
+
+/**
+ * @typedef {import('appium-adb').ADB} ADB
+ */

package/lib/commands/shell.js

@@ -1,56 +1,42 @@
-// @ts-check
-
 import {util} from '@appium/support';
 import {errors} from 'appium/driver';
 import _ from 'lodash';
 import {exec} from 'teen_process';
 import {ADB_SHELL_FEATURE} from '../utils';
-import {mixin} from './mixins';
 
 /**
- * @type {import('./mixins').ShellMixin & ThisType<import('../driver').AndroidDriver>}
- * @satisfies {import('@appium/types').ExternalDriver}
+ * @this {import('../driver').AndroidDriver}
+ * @param {import('./types').ShellOpts} [opts={}]
+ * @returns {Promise<string | {stderr: string; stdout: string}>};
  */
-const ShellMixin = {
-  async mobileShell(opts) {
-    this.ensureFeatureEnabled(ADB_SHELL_FEATURE);
-    const {
-      command,
-      args = /** @type {string[]} */ ([]),
-      timeout = 20000,
-      includeStderr,
-    } = opts ?? {};
+export async function mobileShell(opts) {
+  this.ensureFeatureEnabled(ADB_SHELL_FEATURE);
+  const {command, args = /** @type {string[]} */ ([]), timeout = 20000, includeStderr} = opts ?? {};
 
-    if (!_.isString(command)) {
-      throw new errors.InvalidArgumentError(`The 'command' argument is mandatory`);
-    }
+  if (!_.isString(command)) {
+    throw new errors.InvalidArgumentError(`The 'command' argument is mandatory`);
+  }
 
-    const adbArgs = [...this.adb.executable.defaultArgs, 'shell', command, ..._.castArray(args)];
-    this.log.debug(`Running '${this.adb.executable.path} ${util.quote(adbArgs)}'`);
-    try {
-      const {stdout, stderr} = await exec(this.adb.executable.path, adbArgs, {timeout});
-      if (includeStderr) {
-        return {
-          stdout,
-          stderr,
-        };
-      }
-      return stdout;
-    } catch (e) {
-      const err = /** @type {import('teen_process').ExecError} */ (e);
-      this.log.errorAndThrow(
-        `Cannot execute the '${command}' shell command. ` +
-          `Original error: ${err.message}. ` +
-          `StdOut: ${err.stdout}. StdErr: ${err.stderr}`
-      );
-      throw new Error(); // unreachable; for TS
+  const adbArgs = [...this.adb.executable.defaultArgs, 'shell', command, ..._.castArray(args)];
+  this.log.debug(`Running '${this.adb.executable.path} ${util.quote(adbArgs)}'`);
+  try {
+    const {stdout, stderr} = await exec(this.adb.executable.path, adbArgs, {timeout});
+    if (includeStderr) {
+      return {
+        stdout,
+        stderr,
+      };
     }
-  },
-};
-
-mixin(ShellMixin);
-
-export default ShellMixin;
+    return stdout;
+  } catch (e) {
+    const err = /** @type {import('teen_process').ExecError} */ (e);
+    throw this.log.errorAndThrow(
+      `Cannot execute the '${command}' shell command. ` +
+        `Original error: ${err.message}. ` +
+        `StdOut: ${err.stdout}. StdErr: ${err.stderr}`,
+    );
+  }
+}
 
 /**
  * @typedef {import('appium-adb').ADB} ADB