io.appium.settings 5.3.0 → 5.4.0

package/lib/client.js

@@ -0,0 +1,155 @@
+import { log, LOG_PREFIX } from './logger';
+import _ from 'lodash';
+import { waitForCondition } from 'asyncbox';
+import { SETTINGS_HELPER_ID, SETTINGS_HELPER_MAIN_ACTIVITY } from './constants.js';
+import { setAnimationState } from './commands/animation';
+import { getClipboard } from './commands/clipboard';
+import { setGeoLocation, getGeoLocation, refreshGeoLocationCache } from './commands/geolocation';
+import { setDeviceSysLocale } from './commands/locale';
+import { scanMedia } from './commands/media';
+import { setDataState, setWifiState } from './commands/network';
+import { getNotifications } from './commands/notifications';
+import { getSmsList } from './commands/sms';
+import { performEditorAction, typeUnicode } from './commands/typing';
+
+/**
+ * @typedef {Object} SettingsAppOpts
+ * @property {import('appium-adb').ADB} adb
+ */
+
+
+export class SettingsApp {
+  /** @type {import('appium-adb').ADB} */
+  adb;
+
+  /** @type {import('npmlog').Logger} */
+  log;
+
+  /**
+   * @param {SettingsAppOpts} opts
+   */
+  constructor (opts) {
+    this.adb = opts.adb;
+    this.log = log;
+  }
+
+  /**
+   * @typedef {Object} SettingsAppStartupOptions
+   * @property {number} [timeout=5000] The maximum number of milliseconds
+   * to wait until the app has started
+   * @property {boolean} [shouldRestoreCurrentApp=false] Whether to restore
+   * the activity which was the current one before Settings startup
+   */
+
+  /**
+   * Ensures that Appium Settings helper application is running
+   * and starts it if necessary
+   *
+   * @param {SettingsAppStartupOptions} [opts={}]
+   * @throws {Error} If Appium Settings has failed to start
+   * @returns {Promise<SettingsApp>} self instance for chaining
+   */
+  async requireRunning (opts = {}) {
+    if (await this.adb.processExists(SETTINGS_HELPER_ID)) {
+      return this;
+    }
+
+    this.log.debug(LOG_PREFIX, 'Starting Appium Settings app');
+    const {
+      timeout = 5000,
+      shouldRestoreCurrentApp = false,
+    } = opts;
+    let appPackage;
+    if (shouldRestoreCurrentApp) {
+      try {
+        ({appPackage} = await this.adb.getFocusedPackageAndActivity());
+      } catch (e) {
+        this.log.warn(LOG_PREFIX, `The current application can not be restored: ${e.message}`);
+      }
+    }
+    await this.adb.startApp({
+      pkg: SETTINGS_HELPER_ID,
+      activity: SETTINGS_HELPER_MAIN_ACTIVITY,
+      action: 'android.intent.action.MAIN',
+      category: 'android.intent.category.LAUNCHER',
+      stopApp: false,
+      waitForLaunch: false,
+    });
+    try {
+      await waitForCondition(async () => await this.adb.processExists(SETTINGS_HELPER_ID), {
+        waitMs: timeout,
+        intervalMs: 300,
+      });
+      if (shouldRestoreCurrentApp && appPackage) {
+        try {
+          await this.adb.activateApp(appPackage);
+        } catch (e) {
+          log.warn(`The current application can not be restored: ${e.message}`);
+        }
+      }
+      return this;
+    } catch (err) {
+      throw new Error(`Appium Settings app is not running after ${timeout}ms`);
+    }
+  }
+
+  /**
+   * Parses the output in JSON format retrieved from
+   * the corresponding Appium Settings broadcast calls
+   *
+   * @param {string} output The actual command output
+   * @param {string} entityName The name of the entity which is
+   * going to be parsed
+   * @returns {Object} The parsed JSON object
+   * @throws {Error} If the output cannot be parsed
+   * as a valid JSON
+   */
+  _parseJsonData (output, entityName) {
+    if (!/\bresult=-1\b/.test(output) || !/\bdata="/.test(output)) {
+      this.log.debug(LOG_PREFIX, output);
+      throw new Error(
+        `Cannot retrieve ${entityName} from the device. ` +
+        'Check the server log for more details'
+      );
+    }
+    const match = /\bdata="(.+)",?/.exec(output);
+    if (!match) {
+      this.log.debug(LOG_PREFIX, output);
+      throw new Error(
+        `Cannot parse ${entityName} from the command output. ` +
+        'Check the server log for more details'
+      );
+    }
+    const jsonStr = _.trim(match[1]);
+    try {
+      return JSON.parse(jsonStr);
+    } catch (e) {
+      log.debug(jsonStr);
+      throw new Error(
+        `Cannot parse ${entityName} from the resulting data string. ` +
+        'Check the server log for more details'
+      );
+    }
+  }
+
+  setAnimationState = setAnimationState;
+
+  getClipboard = getClipboard;
+
+  setGeoLocation = setGeoLocation;
+  getGeoLocation = getGeoLocation;
+  refreshGeoLocationCache = refreshGeoLocationCache;
+
+  setDeviceSysLocale = setDeviceSysLocale;
+
+  scanMedia = scanMedia;
+
+  setDataState = setDataState;
+  setWifiState = setWifiState;
+
+  getNotifications = getNotifications;
+  getSmsList = getSmsList;
+
+  performEditorAction = performEditorAction;
+  typeUnicode = typeUnicode;
+}

package/lib/commands/animation.js

@@ -0,0 +1,24 @@
+import { ANIMATION_SETTING_ACTION, ANIMATION_SETTING_RECEIVER } from '../constants.js';
+
+/**
+ * Change the state of animation on the device under test.
+ * Animation on the device is controlled by the following global properties:
+ * [ANIMATOR_DURATION_SCALE]{@link https://developer.android.com/reference/android/provider/Settings.Global.html#ANIMATOR_DURATION_SCALE},
+ * [TRANSITION_ANIMATION_SCALE]{@link https://developer.android.com/reference/android/provider/Settings.Global.html#TRANSITION_ANIMATION_SCALE},
+ * [WINDOW_ANIMATION_SCALE]{@link https://developer.android.com/reference/android/provider/Settings.Global.html#WINDOW_ANIMATION_SCALE}.
+ * This method sets all this properties to 0.0 to disable (1.0 to enable) animation.
+ *
+ * Turning off animation might be useful to improve stability
+ * and reduce tests execution time.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {boolean} on - True to enable and false to disable it.
+ */
+export async function setAnimationState (on) {
+  await this.adb.shell([
+    'am', 'broadcast',
+    '-a', ANIMATION_SETTING_ACTION,
+    '-n', ANIMATION_SETTING_RECEIVER,
+    '--es', 'setstatus', on ? 'enable' : 'disable'
+  ]);
+};

package/lib/commands/clipboard.js

@@ -0,0 +1,47 @@
+import _ from 'lodash';
+import { LOG_PREFIX } from '../logger';
+import {
+  CLIPBOARD_RECEIVER,
+  CLIPBOARD_RETRIEVAL_ACTION,
+  APPIUM_IME
+} from '../constants';
+
+/**
+ * Retrieves the text content of the device's clipboard.
+ * The method works for Android below and above 29.
+ * It temorarily enforces the IME setting in order to workaround
+ * security limitations if needed.
+ * This method only works if Appium Settings v. 2.15+ is installed
+ * on the device under test
+ *
+ * @this {import('../client').SettingsApp}
+ * @returns {Promise<string>} The actual content of the main clipboard as
+ * base64-encoded string or an empty string if the clipboard is empty
+ * @throws {Error} If there was a problem while getting the
+ * clipboard contant
+ */
+export async function getClipboard () {
+  this.log.debug(LOG_PREFIX, 'Getting the clipboard content');
+  await this.requireRunning({shouldRestoreCurrentApp: true});
+  const retrieveClipboard = async () => await this.adb.shell([
+    'am', 'broadcast',
+    '-n', CLIPBOARD_RECEIVER,
+    '-a', CLIPBOARD_RETRIEVAL_ACTION,
+  ]);
+  let output;
+  try {
+    output = (await this.adb.getApiLevel() >= 29)
+      ? (await this.adb.runInImeContext(APPIUM_IME, retrieveClipboard))
+      : (await retrieveClipboard());
+  } catch (err) {
+    throw new Error(`Cannot retrieve the current clipboard content from the device. ` +
+      `Make sure the Appium Settings application is up to date. ` +
+      `Original error: ${err.message}`);
+  }
+
+  const match = /data="([^"]*)"/.exec(output);
+  if (!match) {
+    throw new Error(`Cannot parse the actual cliboard content from the command output: ${output}`);
+  }
+  return _.trim(match[1]);
+};

package/lib/commands/geolocation.js

@@ -0,0 +1,214 @@
+import _ from 'lodash';
+import {
+  LOCATION_SERVICE,
+  LOCATION_RECEIVER,
+  LOCATION_RETRIEVAL_ACTION,
+} from '../constants.js';
+import { SubProcess } from 'teen_process';
+import B from 'bluebird';
+import { LOG_PREFIX } from '../logger.js';
+
+const DEFAULT_SATELLITES_COUNT = 12;
+const DEFAULT_ALTITUDE = 0.0;
+const LOCATION_TRACKER_TAG = 'LocationTracker';
+const GPS_CACHE_REFRESHED_LOGS = [
+  'The current location has been successfully retrieved from Play Services',
+  'The current location has been successfully retrieved from Location Manager'
+];
+
+const GPS_COORDINATES_PATTERN = /data="(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)"/;
+
+/**
+ * @typedef {Object} Location
+ * @property {number|string} longitude - Valid longitude value.
+ * @property {number|string} latitude - Valid latitude value.
+ * @property {?number|string} [altitude] - Valid altitude value.
+ * @property {?number|string} [satellites=12] - Number of satellites being tracked (1-12).
+ * This value is ignored on real devices.
+ * @property {?number|string} [speed] - Valid speed value.
+ * Should be greater than 0.0 meters/second for real devices or 0.0 knots
+ * for emulators.
+ */
+
+/**
+ * Emulate geolocation coordinates on the device under test.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {Location} location - Location object. The `altitude` value is ignored
+ * while mocking the position.
+ * @param {boolean} [isEmulator=false] - Set it to true if the device under test
+ *                                       is an emulator rather than a real device.
+ */
+export async function setGeoLocation (location, isEmulator = false) {
+  const formatLocationValue = (valueName, isRequired = true) => {
+    if (_.isNil(location[valueName])) {
+      if (isRequired) {
+        throw new Error(`${valueName} must be provided`);
+      }
+      return null;
+    }
+    const floatValue = parseFloat(location[valueName]);
+    if (!isNaN(floatValue)) {
+      return `${_.ceil(floatValue, 5)}`;
+    }
+    if (isRequired) {
+      throw new Error(`${valueName} is expected to be a valid float number. ` +
+        `'${location[valueName]}' is given instead`);
+    }
+    return null;
+  };
+  const longitude = /** @type {string} */ (formatLocationValue('longitude'));
+  const latitude = /** @type {string} */ (formatLocationValue('latitude'));
+  const altitude = formatLocationValue('altitude', false);
+  const speed = formatLocationValue('speed', false);
+  if (isEmulator) {
+    /** @type {string[]} */
+    const args = [longitude, latitude];
+    if (!_.isNil(altitude)) {
+      args.push(altitude);
+    }
+    const satellites = parseInt(`${location.satellites}`, 10);
+    if (!Number.isNaN(satellites) && satellites > 0 && satellites <= 12) {
+      if (args.length < 3) {
+        args.push(`${DEFAULT_ALTITUDE}`);
+      }
+      args.push(`${satellites}`);
+    }
+    if (!_.isNil(speed)) {
+      if (args.length < 3) {
+        args.push(`${DEFAULT_ALTITUDE}`);
+      }
+      if (args.length < 4) {
+        args.push(`${DEFAULT_SATELLITES_COUNT}`);
+      }
+      args.push(speed);
+    }
+    await this.adb.resetTelnetAuthToken();
+    await this.adb.adbExec(['emu', 'geo', 'fix', ...args]);
+    // A workaround for https://code.google.com/p/android/issues/detail?id=206180
+    await this.adb.adbExec(['emu', 'geo', 'fix', ...(args.map((arg) => arg.replace('.', ',')))]);
+  } else {
+    const args = [
+      'am', (await this.adb.getApiLevel() >= 26) ? 'start-foreground-service' : 'startservice',
+      '-e', 'longitude', longitude,
+      '-e', 'latitude', latitude,
+    ];
+    if (!_.isNil(altitude)) {
+      args.push('-e', 'altitude', altitude);
+    }
+    if (!_.isNil(speed)) {
+      args.push('-e', 'speed', speed);
+    }
+    args.push(LOCATION_SERVICE);
+    await this.adb.shell(args);
+  }
+};
+
+/**
+ * Get the current cached GPS location from the device under test.
+ *
+ * @this {import('../client').SettingsApp}
+ * @returns {Promise<Location>} The current location
+ * @throws {Error} If the current location cannot be retrieved
+ */
+export async function getGeoLocation () {
+  await this.requireRunning({shouldRestoreCurrentApp: true});
+
+  let output;
+  try {
+    output = await this.adb.shell([
+      'am', 'broadcast',
+      '-n', LOCATION_RECEIVER,
+      '-a', LOCATION_RETRIEVAL_ACTION,
+    ]);
+  } catch (err) {
+    throw new Error(`Cannot retrieve the current geo coordinates from the device. ` +
+      `Make sure the Appium Settings application is up to date and has location permissions. Also the location ` +
+      `services must be enabled on the device. Original error: ${err.stderr || err.stdout || err.message}`);
+  }
+
+  const match = GPS_COORDINATES_PATTERN.exec(output);
+  if (!match) {
+    throw new Error(`Cannot parse the actual location values from the command output: ${output}`);
+  }
+  const location = {
+    latitude: match[1],
+    longitude: match[2],
+    altitude: match[3],
+  };
+  this.log.debug(LOG_PREFIX, `Got geo coordinates: ${JSON.stringify(location)}`);
+  return location;
+};
+
+/**
+ * Sends an async request to refresh the GPS cache.
+ * This feature only works if the device under test has
+ * Google Play Services installed. In case the vanilla
+ * LocationManager is used the device API level must be at
+ * version 30 (Android R) or higher.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {number} timeoutMs The maximum number of milliseconds
+ * to block until GPS cache is refreshed. Providing zero or a negative
+ * value to it skips waiting completely.
+ *
+ * @throws {Error} If the GPS cache cannot be refreshed.
+ */
+export async function refreshGeoLocationCache (timeoutMs = 20000) {
+  await this.requireRunning({shouldRestoreCurrentApp: true});
+
+  let logcatMonitor;
+  let monitoringPromise;
+
+  if (timeoutMs > 0) {
+    const cmd = [
+      ...this.adb.executable.defaultArgs,
+      'logcat', '-s', LOCATION_TRACKER_TAG,
+    ];
+    logcatMonitor = new SubProcess(this.adb.executable.path, cmd);
+    const timeoutErrorMsg = `The GPS cache has not been refreshed within ${timeoutMs}ms timeout. ` +
+      `Please make sure the device under test has Appium Settings app installed and running. ` +
+      `Also, it is required that the device has Google Play Services installed or is running ` +
+      `Android 10+ otherwise.`;
+    monitoringPromise = new B((resolve, reject) => {
+      setTimeout(() => reject(new Error(timeoutErrorMsg)), timeoutMs);
+
+      logcatMonitor.on('exit', () => reject(new Error(timeoutErrorMsg)));
+      ['lines-stderr', 'lines-stdout'].map((evt) => logcatMonitor.on(evt, (lines) => {
+        if (lines.some((line) => GPS_CACHE_REFRESHED_LOGS.some((x) => line.includes(x)))) {
+          resolve();
+        }
+      }));
+    });
+    await logcatMonitor.start(0);
+  }
+
+  try {
+    await this.adb.shell([
+      'am', 'broadcast',
+      '-n', LOCATION_RECEIVER,
+      '-a', LOCATION_RETRIEVAL_ACTION,
+      '--ez', 'forceUpdate', 'true',
+    ]);
+  } catch (err) {
+    throw new Error(`Cannot refresh the GPS cache on the device. ` +
+      `Make sure the Appium Settings application is up to date and has location permissions. Also the location ` +
+      `services must be enabled on the device. Original error: ${err.stderr || err.stdout || err.message}`);
+  }
+
+  if (logcatMonitor && monitoringPromise) {
+    const startMs = performance.now();
+    this.log.debug(LOG_PREFIX, `Waiting up to ${timeoutMs}ms for the GPS cache to be refreshed`);
+    try {
+      await monitoringPromise;
+      this.log.info(LOG_PREFIX, `The GPS cache has been successfully refreshed after ` +
+        `${(performance.now() - startMs).toFixed(0)}ms`);
+    } finally {
+      if (logcatMonitor.isRunning) {
+        await logcatMonitor.stop();
+      }
+    }
+  } else {
+    this.log.info(LOG_PREFIX, 'The request to refresh the GPS cache has been sent. Skipping waiting for its result.');
+  }
+};

package/lib/commands/locale.js

@@ -0,0 +1,28 @@
+import { LOCALE_SETTING_ACTION, LOCALE_SETTING_RECEIVER } from '../constants.js';
+
+/**
+ * Change the locale on the device under test. Don't need to reboot the device after changing the locale.
+ * This method sets an arbitrary locale following:
+ *   https://developer.android.com/reference/java/util/Locale.html
+ *   https://developer.android.com/reference/java/util/Locale.html#Locale(java.lang.String,%20java.lang.String)
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {string} language - Language. e.g. en, ja
+ * @param {string} country - Country. e.g. US, JP
+ * @param {string?} [script=null] - Script. e.g. Hans in `zh-Hans-CN`
+ */
+export async function setDeviceSysLocale (language, country, script = null) {
+  const params = [
+    'am', 'broadcast',
+    '-a', LOCALE_SETTING_ACTION,
+    '-n', LOCALE_SETTING_RECEIVER,
+    '--es', 'lang', language.toLowerCase(),
+    '--es', 'country', country.toUpperCase()
+  ];
+
+  if (script) {
+    params.push('--es', 'script', script);
+  }
+
+  await this.adb.shell(params);
+};

package/lib/commands/media.js

@@ -0,0 +1,27 @@
+import _ from 'lodash';
+import { LOG_PREFIX } from '../logger.js';
+import { MEDIA_SCAN_ACTION, MEDIA_SCAN_RECEIVER } from '../constants.js';
+
+/**
+ * Performs recursive media scan at the given destination.
+ * All successfully scanned items are being added to the device's
+ * media library.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {string} destination File/folder path on the remote device.
+ * @throws {Error} If there was an unexpected error by scanning.
+ */
+export async function scanMedia (destination) {
+  this.log.debug(LOG_PREFIX, `Scanning '${destination}' for media files`);
+  await this.requireRunning({shouldRestoreCurrentApp: true});
+  const output = await this.adb.shell([
+    'am', 'broadcast',
+    '-n', MEDIA_SCAN_RECEIVER,
+    '-a', MEDIA_SCAN_ACTION,
+    '--es', 'path', destination
+  ]);
+  if (!_.includes(output, 'result=-1')) {
+    throw new Error(`No media could be scanned at '${destination}'. ` +
+      `Check the device logcat output for more details.`);
+  }
+};

package/lib/commands/network.js

@@ -0,0 +1,73 @@
+import {
+  WIFI_CONNECTION_SETTING_ACTION,
+  WIFI_CONNECTION_SETTING_RECEIVER,
+  DATA_CONNECTION_SETTING_ACTION,
+  DATA_CONNECTION_SETTING_RECEIVER,
+} from '../constants.js';
+
+/**
+ * Change the state of WiFi on the device under test.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {boolean} on - True to enable and false to disable it.
+ * @param {boolean} [isEmulator=false] - Set it to true if the device under test
+ *                                       is an emulator rather than a real device.
+ */
+export async function setWifiState (on, isEmulator = false) {
+  if (isEmulator) {
+    // The svc command does not require to be root since API 26
+    await this.adb.shell(['svc', 'wifi', on ? 'enable' : 'disable'], {
+      privileged: await this.adb.getApiLevel() < 26,
+    });
+    return;
+  }
+
+  if (await this.adb.getApiLevel() < 30) {
+    // Android below API 30 does not have a dedicated adb command
+    // to manipulate wifi connection state, so try to do it via Settings app
+    // as a workaround
+    await this.requireRunning({shouldRestoreCurrentApp: true});
+
+    await this.adb.shell([
+      'am', 'broadcast',
+      '-a', WIFI_CONNECTION_SETTING_ACTION,
+      '-n', WIFI_CONNECTION_SETTING_RECEIVER,
+      '--es', 'setstatus', on ? 'enable' : 'disable'
+    ]);
+    return;
+  }
+
+  await this.adb.shell(['cmd', '-w', 'wifi', 'set-wifi-enabled', on ? 'enabled' : 'disabled']);
+};
+
+/**
+ * Change the state of Data transfer on the device under test.
+ *
+ * @this {import('../client').SettingsApp}
+ * @param {boolean} on - True to enable and false to disable it.
+ * @param {boolean} [isEmulator=false] - Set it to true if the device under test
+ *                                       is an emulator rather than a real device.
+ */
+export async function setDataState (on, isEmulator = false) {
+  if (isEmulator) {
+    // The svc command does not require to be root since API 26
+    await this.adb.shell(['svc', 'data', on ? 'enable' : 'disable'], {
+      privileged: await this.adb.getApiLevel() < 26,
+    });
+    return;
+  }
+
+  if (await this.adb.getApiLevel() < 30) {
+    await this.requireRunning({shouldRestoreCurrentApp: true});
+
+    await this.adb.shell([
+      'am', 'broadcast',
+      '-a', DATA_CONNECTION_SETTING_ACTION,
+      '-n', DATA_CONNECTION_SETTING_RECEIVER,
+      '--es', 'setstatus', on ? 'enable' : 'disable'
+    ]);
+    return;
+  }
+
+  await this.adb.shell(['cmd', 'phone', 'data', on ? 'enable' : 'disable']);
+};

package/lib/commands/notifications.js

@@ -0,0 +1,71 @@
+import { LOG_PREFIX } from '../logger';
+import { NOTIFICATIONS_RETRIEVAL_ACTION } from '../constants';
+
+/**
+ * Retrieves Android notifications via Appium Settings helper.
+ * Appium Settings app itself must be *manually* granted to access notifications
+ * under device Settings in order to make this feature working.
+ * Appium Settings helper keeps all the active notifications plus
+ * notifications that appeared while it was running in the internal buffer,
+ * but no more than 100 items altogether. Newly appeared notifications
+ * are always added to the head of the notifications array.
+ * The `isRemoved` flag is set to `true` for notifications that have been removed.
+ *
+ * See https://developer.android.com/reference/android/service/notification/StatusBarNotification
+ * and https://developer.android.com/reference/android/app/Notification.html
+ * for more information on available notification properties and their values.
+ *
+ * @this {import('../client').SettingsApp}
+ * @returns {Promise<Record<string, any>>} The example output is:
+ * ```json
+ * {
+ *   "statusBarNotifications":[
+ *     {
+ *       "isGroup":false,
+ *       "packageName":"io.appium.settings",
+ *       "isClearable":false,
+ *       "isOngoing":true,
+ *       "id":1,
+ *       "tag":null,
+ *       "notification":{
+ *         "title":null,
+ *         "bigTitle":"Appium Settings",
+ *         "text":null,
+ *         "bigText":"Keep this service running, so Appium for Android can properly interact with several system APIs",
+ *         "tickerText":null,
+ *         "subText":null,
+ *         "infoText":null,
+ *         "template":"android.app.Notification$BigTextStyle"
+ *       },
+ *       "userHandle":0,
+ *       "groupKey":"0|io.appium.settings|1|null|10133",
+ *       "overrideGroupKey":null,
+ *       "postTime":1576853518850,
+ *       "key":"0|io.appium.settings|1|null|10133",
+ *       "isRemoved":false
+ *     }
+ *   ]
+ * }
+ * ```
+ * @throws {Error} If there was an error while getting the notifications list
+ */
+export async function getNotifications () {
+  this.log.debug(LOG_PREFIX, 'Retrieving notifications');
+  // Somehow providing the `-n` arg to the `am` underneath
+  // renders the broadcast to fail instead of starting the
+  // Appium Settings app. This only happens to the notifications
+  // receiver
+  await this.requireRunning({shouldRestoreCurrentApp: true});
+  let output;
+  try {
+    output = await this.adb.shell([
+      'am', 'broadcast',
+      '-a', NOTIFICATIONS_RETRIEVAL_ACTION,
+    ]);
+  } catch (err) {
+    throw new Error(`Cannot retrieve notifications from the device. ` +
+      `Make sure the Appium Settings application is installed and is up to date. ` +
+      `Original error: ${err.message}`);
+  }
+  return this._parseJsonData(output, 'notifications');
+};