appium-android-driver 12.4.8 → 12.4.9

package/lib/commands/{network.js → network.ts}

@@ -1,7 +1,9 @@
 import _ from 'lodash';
 import {errors} from 'appium/driver';
-import {util} from 'appium/support';
+import {util} from '@appium/support';
 import B from 'bluebird';
+import type {AndroidDriver} from '../driver';
+import type {ServiceType, GetConnectivityResult} from './types';
 
 const AIRPLANE_MODE_MASK = 0b001;
 const WIFI_MASK = 0b010;
@@ -9,26 +11,33 @@ const DATA_MASK = 0b100;
 const WIFI_KEY_NAME = 'wifi';
 const DATA_KEY_NAME = 'data';
 const AIRPLANE_MODE_KEY_NAME = 'airplaneMode';
-const SUPPORTED_SERVICE_NAMES = /** @type {import('./types').ServiceType[]} */ ([
+const SUPPORTED_SERVICE_NAMES: ServiceType[] = [
   WIFI_KEY_NAME,
   DATA_KEY_NAME,
   AIRPLANE_MODE_KEY_NAME,
-]);
+];
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<number>}
+ * Gets the current network connection state.
+ *
+ * @returns Promise that resolves to a number representing the network connection state.
+ * The value is a bitmask where:
+ * - Bit 0 (0b001) = Airplane mode
+ * - Bit 1 (0b010) = Wi-Fi
+ * - Bit 2 (0b100) = Data connection
  */
-export async function getNetworkConnection() {
+export async function getNetworkConnection(
+  this: AndroidDriver,
+): Promise<number> {
   this.log.info('Getting network connection');
-  let airplaneModeOn = await this.adb.isAirplaneModeOn();
+  const airplaneModeOn = await this.adb.isAirplaneModeOn();
   let connection = airplaneModeOn ? AIRPLANE_MODE_MASK : 0;
 
   // no need to check anything else if we are in airplane mode
   if (!airplaneModeOn) {
-    let wifiOn = await this.isWifiOn();
+    const wifiOn = await this.isWifiOn();
     connection |= wifiOn ? WIFI_MASK : 0;
-    let dataOn = await this.adb.isDataOn();
+    const dataOn = await this.adb.isDataOn();
     connection |= dataOn ? DATA_MASK : 0;
   }
 
@@ -36,40 +45,53 @@ export async function getNetworkConnection() {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<boolean>}
+ * Checks if Wi-Fi is enabled.
+ *
+ * @returns Promise that resolves to `true` if Wi-Fi is enabled, `false` otherwise.
  */
-export async function isWifiOn() {
+export async function isWifiOn(
+  this: AndroidDriver,
+): Promise<boolean> {
   return await this.adb.isWifiOn();
 }
 
 /**
+ * Sets the connectivity state for Wi-Fi, data, and/or airplane mode.
+ *
  * @since Android 12 (only real devices, emulators work in all APIs)
- * @this {import('../driver').AndroidDriver}
- * @param {boolean} [wifi] Either to enable or disable Wi-Fi.
+ * @param wifi Either to enable or disable Wi-Fi.
  * An unset value means to not change the state for the given service.
- * @param {boolean} [data] Either to enable or disable mobile data connection.
+ * @param data Either to enable or disable mobile data connection.
  * An unset value means to not change the state for the given service.
- * @param {boolean} [airplaneMode] Either to enable to disable the Airplane Mode
+ * @param airplaneMode Either to enable to disable the Airplane Mode.
  * An unset value means to not change the state for the given service.
- * @returns {Promise<void>}
+ * @returns Promise that resolves when the connectivity state is set.
+ * @throws {errors.InvalidArgumentError} If none of the options are provided.
  */
-export async function mobileSetConnectivity(wifi, data, airplaneMode) {
+export async function mobileSetConnectivity(
+  this: AndroidDriver,
+  wifi?: boolean,
+  data?: boolean,
+  airplaneMode?: boolean,
+): Promise<void> {
   if (_.every([wifi, data, airplaneMode], _.isUndefined)) {
     throw new errors.InvalidArgumentError(
       `Either one of ${JSON.stringify(SUPPORTED_SERVICE_NAMES)} options must be provided`,
     );
   }
 
-  const currentState = await this.mobileGetConnectivity(
-    /** @type {import('./types').ServiceType[]} */ ([
-      ...(_.isUndefined(wifi) ? [] : [WIFI_KEY_NAME]),
-      ...(_.isUndefined(data) ? [] : [DATA_KEY_NAME]),
-      ...(_.isUndefined(airplaneMode) ? [] : [AIRPLANE_MODE_KEY_NAME]),
-    ]),
-  );
-  /** @type {(Promise<any>|(() => Promise<any>))[]} */
-  const setters = [];
+  const services: ServiceType[] = [
+    [wifi, WIFI_KEY_NAME],
+    [data, DATA_KEY_NAME],
+    [airplaneMode, AIRPLANE_MODE_KEY_NAME],
+  ].reduce<ServiceType[]>((acc, [value, key]: [boolean | undefined, ServiceType]) => {
+    if (!_.isUndefined(value)) {
+      acc.push(key);
+    }
+    return acc;
+  }, []);
+  const currentState = await this.mobileGetConnectivity(services);
+  const setters: Array<Promise<any> | (() => Promise<any>)> = [];
   if (!_.isUndefined(wifi) && currentState.wifi !== Boolean(wifi)) {
     setters.push(this.setWifiState(wifi));
   }
@@ -90,12 +112,16 @@ export async function mobileSetConnectivity(wifi, data, airplaneMode) {
 }
 
 /**
- * @this {import('../driver').AndroidDriver}
- * @param {import('./types').ServiceType[] | import('./types').ServiceType} [services] one or more
- * services to get the connectivity for.
- * @returns {Promise<import('./types').GetConnectivityResult>}
+ * Gets the connectivity state for one or more services.
+ *
+ * @param services One or more services to get the connectivity for.
+ * @returns Promise that resolves to an object containing the connectivity state for the requested services.
+ * @throws {errors.InvalidArgumentError} If any of the provided service names are not supported.
  */
-export async function mobileGetConnectivity(services = SUPPORTED_SERVICE_NAMES) {
+export async function mobileGetConnectivity(
+  this: AndroidDriver,
+  services: ServiceType[] | ServiceType = SUPPORTED_SERVICE_NAMES,
+): Promise<GetConnectivityResult> {
   const svcs = _.castArray(services);
   const unsupportedServices = _.difference(svcs, SUPPORTED_SERVICE_NAMES);
   if (!_.isEmpty(unsupportedServices)) {
@@ -123,17 +149,25 @@ export async function mobileGetConnectivity(services = SUPPORTED_SERVICE_NAMES)
   return _.reduce(
     statePromises,
     (state, v, k) => _.isUndefined(v.value()) ? state : {...state, [k]: Boolean(v.value())},
-    {}
+    {} as GetConnectivityResult,
   );
 }
 
 /**
+ * Sets the network connection state using a bitmask.
+ *
  * @since Android 12 (only real devices, emulators work in all APIs)
- * @this {import('../driver').AndroidDriver}
- * @param {number} type
- * @returns {Promise<number>}
+ * @param type A number representing the desired network connection state.
+ * The value is a bitmask where:
+ * - Bit 0 (0b001) = Airplane mode
+ * - Bit 1 (0b010) = Wi-Fi
+ * - Bit 2 (0b100) = Data connection
+ * @returns Promise that resolves to the current network connection state after the change.
  */
-export async function setNetworkConnection(type) {
+export async function setNetworkConnection(
+  this: AndroidDriver,
+  type: number,
+): Promise<number> {
   this.log.info('Setting network connection');
   // decode the input
   const shouldEnableAirplaneMode = (type & AIRPLANE_MODE_MASK) !== 0;
@@ -192,61 +226,74 @@ export async function setNetworkConnection(type) {
 }
 
 /**
+ * Sets the Wi-Fi state.
+ *
  * @since Android 12 (only real devices, emulators work in all APIs)
- * @this {import('../driver').AndroidDriver}
- * @param {boolean} isOn
- * @returns {Promise<void>}
+ * @param isOn `true` to enable Wi-Fi, `false` to disable it.
+ * @returns Promise that resolves when the Wi-Fi state is set.
  */
-export async function setWifiState(isOn) {
+export async function setWifiState(
+  this: AndroidDriver,
+  isOn: boolean,
+): Promise<void> {
   await this.settingsApp.setWifiState(isOn, this.isEmulator());
 }
 
 /**
+ * Sets the mobile data connection state.
+ *
  * @since Android 12 (only real devices, emulators work in all APIs)
- * @this {import('../driver').AndroidDriver}
- * @param {boolean} isOn
- * @returns {Promise<void>}
+ * @param isOn `true` to enable mobile data, `false` to disable it.
+ * @returns Promise that resolves when the data connection state is set.
  */
-export async function setDataState(isOn) {
+export async function setDataState(
+  this: AndroidDriver,
+  isOn: boolean,
+): Promise<void> {
   await this.settingsApp.setDataState(isOn, this.isEmulator());
 }
 
 /**
+ * Toggles the mobile data connection state.
+ *
  * @since Android 12 (only real devices, emulators work in all APIs)
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * @returns Promise that resolves when the data connection state is toggled.
  */
-export async function toggleData() {
+export async function toggleData(
+  this: AndroidDriver,
+): Promise<void> {
   const isOn = await this.adb.isDataOn();
   this.log.info(`Turning network data ${!isOn ? 'on' : 'off'}`);
   await this.setDataState(!isOn);
 }
 
 /**
+ * Toggles the Wi-Fi state.
+ *
  * @since Android 12 (only real devices, emulators work in all APIs)
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * @returns Promise that resolves when the Wi-Fi state is toggled.
  */
-export async function toggleWiFi() {
+export async function toggleWiFi(
+  this: AndroidDriver,
+): Promise<void> {
   const isOn = await this.adb.isWifiOn();
   this.log.info(`Turning WiFi ${!isOn ? 'on' : 'off'}`);
   await this.setWifiState(!isOn);
 }
 
 /**
+ * Toggles the airplane mode state.
+ *
  * @since Android 12 (only real devices, emulators work in all APIs)
- * @this {import('../driver').AndroidDriver}
- * @returns {Promise<void>}
+ * @returns Promise that resolves when the airplane mode state is toggled.
  */
-export async function toggleFlightMode() {
-  let flightMode = !(await this.adb.isAirplaneModeOn());
+export async function toggleFlightMode(
+  this: AndroidDriver,
+): Promise<void> {
+  const flightMode = !(await this.adb.isAirplaneModeOn());
   this.log.info(`Turning flight mode ${flightMode ? 'on' : 'off'}`);
   await this.adb.setAirplaneMode(flightMode);
   if ((await this.adb.getApiLevel()) < 30) {
     await this.adb.broadcastAirplaneMode(flightMode);
   }
 }
-
-/**
- * @typedef {import('appium-adb').ADB} ADB
- */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-android-driver",
-  "version": "12.4.8",
+  "version": "12.4.9",
   "description": "Android UiAutomator and Chrome support for Appium",
   "keywords": [
     "appium",