Add Appium-specific commands. (#3492)

lib/api/client-commands/setGeolocation.js

@@ -35,7 +35,6 @@ class SetGeolocation extends ClientCommand {
   }
 
   performAction(callback) {
-
     if (!this.api.isChrome()  && !this.api.isEdge()) {
       const error =  new Error('The command .setGeolocation() is only supported in Chrome and Edge drivers');
       Logger.error(error);

lib/api/protocol/appium/getCurrentActivity.js

@@ -0,0 +1,33 @@
+const ProtocolAction = require('../_base-action.js');
+
+/**
+ * Get the name of the current Android activity.
+ *
+ * @example
+ * module.exports = {
+ *   'get current activity name': function (app) {
+ *     app
+ *       .appium.getCurrentActivity(function (result) {
+ *         console.log('current android activity is:', result.value);
+ *       });
+ *   },
+ *
+ *   'get current activity name with ES6 async/await': async function (app) {
+ *     const activity = await app.appium.getCurrentActivity();
+ *     console.log('current android activity is:', activity);
+ *   }
+ * };
+ *
+ * @syntax .appium.getCurrentActivity([callback])
+ * @method getCurrentActivity
+ * @param {function} [callback] Callback function which is called with the result value.
+ * @returns {string} Name of the current activity.
+ * @see appium.getCurrentPackage
+ * @see appium.startActivity
+ * @api protocol.appium
+ */
+module.exports = class Session extends ProtocolAction {
+  command(callback) {
+    return this.transportActions.getCurrentActivity(callback);
+  }
+};

lib/api/protocol/appium/getCurrentPackage.js

@@ -0,0 +1,33 @@
+const ProtocolAction = require('../_base-action.js');
+
+/**
+ * Get the name of the current Android package.
+ *
+ * @example
+ * module.exports = {
+ *   'get current package name': function (app) {
+ *     app
+ *       .appium.getCurrentPackage(function (result) {
+ *         console.log('current android package is:', result.value);
+ *       });
+ *   },
+ *
+ *   'get current package name with ES6 async/await': async function (app) {
+ *     const packageName = await app.appium.getCurrentPackage();
+ *     console.log('current android package is:', packageName);
+ *   }
+ * };
+ *
+ * @syntax .appium.getCurrentPackage([callback])
+ * @method getCurrentPackage
+ * @param {function} [callback] Callback function which is called with the result value.
+ * @returns {string} Name of the current package.
+ * @see appium.getCurrentActivity
+ * @see appium.startActivity
+ * @api protocol.appium
+ */
+module.exports = class Session extends ProtocolAction {
+  command(callback) {
+    return this.transportActions.getCurrentPackage(callback);
+  }
+};

lib/api/protocol/appium/getGeolocation.js

@@ -0,0 +1,32 @@
+const ProtocolAction = require('../_base-action.js');
+
+/**
+ * Get the current geolocation of the mobile device.
+ *
+ * @example
+ * module.exports = {
+ *   'get device geolocation': function (app) {
+ *     app
+ *       .appium.getGeolocation(function (result) {
+ *         console.log('current device geolocation is:', result.value);
+ *       });
+ *   },
+ *
+ *   'get device geolocation with ES6 async/await': async function (app) {
+ *     const location = await app.appium.getGeolocation();
+ *     console.log('current device geolocation is:', location);
+ *   }
+ * };
+ *
+ * @syntax .appium.getGeolocation([callback])
+ * @method getGeolocation
+ * @param {function} [callback] Callback function which is called with the result value.
+ * @returns {object} The current geolocation: `{latitude: number, longitude: number, altitude: number}`.
+ * @see appium.setGeolocation
+ * @api protocol.appium
+ */
+module.exports = class Session extends ProtocolAction {
+  command(callback) {
+    return this.transportActions.getDeviceGeolocation(callback);
+  }
+};

lib/api/protocol/appium/getOrientation.js

@@ -0,0 +1,32 @@
+const ProtocolAction = require('../_base-action.js');
+
+/**
+ * Get the current device orientation.
+ *
+ * @example
+ * module.exports = {
+ *   'get current device orientation': function (app) {
+ *     app
+ *       .appium.getOrientation(function (result) {
+ *         console.log('current device orientation is:', result.value);
+ *       });
+ *   },
+ *
+ *   'get current device orientation with ES6 async/await': async function (app) {
+ *     const orientation = await app.appium.getOrientation();
+ *     console.log('current device orientation is:', orientation);
+ *   }
+ * };
+ *
+ * @syntax .appium.getOrientation([callback])
+ * @method getOrientation
+ * @param {function} callback Callback function which is called with the result value.
+ * @returns {string} The current device orientation: `LANDSCAPE` or `PORTRAIT`.
+ * @see appium.setOrientation
+ * @api protocol.appium
+ */
+module.exports = class Session extends ProtocolAction {
+  command(callback) {
+    return this.transportActions.getScreenOrientation(callback);
+  }
+};

lib/api/protocol/appium/hideKeyboard.js

@@ -0,0 +1,32 @@
+const ProtocolAction = require('../_base-action.js');
+
+/**
+ * Hide soft keyboard.
+ *
+ * @example
+ * module.exports = {
+ *   'hide device soft keyboard': function (app) {
+ *     app
+ *       .appium.hideKeyboard();
+ *   },
+ *
+ *   'hide device soft keyboard with ES6 async/await': async function (app) {
+ *     await app.appium.hideKeyboard();
+ *   }
+ * };
+ *
+ * @syntax .appium.hideKeyboard([callback])
+ * @method hideKeyboard
+ * @param {function} [callback] Optional callback function to be called when the command finishes.
+ * @see appium.isKeyboardShown
+ * @api protocol.appium
+ */
+module.exports = class Session extends ProtocolAction {
+  static get isTraceable() {
+    return true;
+  }
+
+  command(callback) {
+    return this.transportActions.hideDeviceKeyboard({}, callback);
+  }
+};

lib/api/protocol/appium/isKeyboardShown.js

@@ -0,0 +1,32 @@
+const ProtocolAction = require('../_base-action.js');
+
+/**
+ * Whether or not the soft keyboard is shown.
+ *
+ * @example
+ * module.exports = {
+ *   'whether keyboard is shown': function (app) {
+ *     app
+ *       .appium.isKeyboardShown(function (result) {
+ *         console.log('result value of whether keyboard is shown:', result.value);
+ *       });
+ *   },
+ *
+ *   'whether keyboard is shown with ES6 async/await': async function (app) {
+ *     const result = await app.appium.isKeyboardShown();
+ *     console.log('result value of whether keyboard is shown:', result);
+ *   }
+ * };
+ *
+ * @syntax .appium.isKeyboardShown([callback])
+ * @method isKeyboardShown
+ * @param {function} [callback] Callback function which is called with the result value.
+ * @returns {boolean} True if the keyboard is shown.
+ * @see appium.hideKeyboard
+ * @api protocol.appium
+ */
+module.exports = class Session extends ProtocolAction {
+  command(callback) {
+    return this.transportActions.isDeviceKeyboardShown(callback);
+  }
+};

lib/api/protocol/appium/longPressKeyCode.js

@@ -0,0 +1,58 @@
+const ProtocolAction = require('../_base-action.js');
+
+/**
+ * Press and hold a particular key on an Android Device.
+ *
+ * See [official Android Developers docs](https://developer.android.com/reference/android/view/KeyEvent.html) for reference of available Android key code values.
+ *
+ * @example
+ * module.exports = {
+ *   'long press e with caps lock on (keycode 33 and metastate 1048576)': function (app) {
+ *     app
+ *       .appium.longPressKeyCode(33, 1048576);
+ *   },
+ *
+ *   'long press g (keycode 35) with ES6 async/await': async function (app) {
+ *     await app.appium.longPressKeyCode(35);
+ *   }
+ * };
+ *
+ * @syntax .appium.longPressKeyCode(keycode, [callback])
+ * @syntax .appium.longPressKeyCode(keycode, metastate, flags, [callback])
+ * @method longPressKeyCode
+ * @param {number} keycode Key code to press on the device.
+ * @param {number} [metastate] Meta state to press the keycode with.
+ * @param {number} [flags] Flags for the keypress.
+ * @param {function} [callback] Optional callback function to be called when the command finishes.
+ * @see appium.pressKeyCode
+ * @api protocol.appium
+ */
+module.exports = class Session extends ProtocolAction {
+  static get isTraceable() {
+    return true;
+  }
+
+  command(keycode, ...args) {
+    let metastate;
+    let flags;
+    let callback;
+
+    if (typeof keycode !== 'number') {
+      throw new Error('The first argument to longPressKeyCode is mandatory and must be a number.');
+    }
+
+    if (typeof args[0] === 'function') {
+      callback = args[0];
+    } else {
+      [metastate, flags, callback] = args;
+    }
+
+    const opts = {
+      keycode,
+      ...(metastate && {metastate}),
+      ...(flags && {flags})
+    };
+
+    return this.transportActions.longPressDeviceKeyCode(opts, callback);
+  }
+};

lib/api/protocol/appium/pressKeyCode.js

@@ -0,0 +1,58 @@
+const ProtocolAction = require('../_base-action.js');
+
+/**
+ * Press a particular key on an Android Device.
+ *
+ * See [official Android Developers docs](https://developer.android.com/reference/android/view/KeyEvent.html) for reference of available Android key code values.
+ *
+ * @example
+ * module.exports = {
+ *   'press e with caps lock on (keycode 33 and metastate 1048576)': function (app) {
+ *     app
+ *       .appium.pressKeyCode(33, 1048576);
+ *   },
+ *
+ *   'press g (keycode 35) with ES6 async/await': async function (app) {
+ *     await app.appium.pressKeyCode(35);
+ *   }
+ * };
+ *
+ * @syntax .appium.pressKeyCode(keycode, [callback])
+ * @syntax .appium.pressKeyCode(keycode, metastate, flags, [callback])
+ * @method pressKeyCode
+ * @param {number} keycode Key code to press on the device.
+ * @param {number} [metastate] Meta state to press the keycode with.
+ * @param {number} [flags] Flags for the keypress.
+ * @param {function} [callback] Optional callback function to be called when the command finishes.
+ * @see appium.longPressKeyCode
+ * @api protocol.appium
+ */
+module.exports = class Session extends ProtocolAction {
+  static get isTraceable() {
+    return true;
+  }
+
+  command(keycode, ...args) {
+    let metastate;
+    let flags;
+    let callback;
+
+    if (typeof keycode !== 'number') {
+      throw new Error('The first argument to pressKeyCode is mandatory and must be a number.');
+    }
+
+    if (typeof args[0] === 'function') {
+      callback = args[0];
+    } else {
+      [metastate, flags, callback] = args;
+    }
+
+    const opts = {
+      keycode,
+      ...(metastate && {metastate}),
+      ...(flags && {flags})
+    };
+
+    return this.transportActions.pressDeviceKeyCode(opts, callback);
+  }
+};

lib/api/protocol/appium/setGeolocation.js

@@ -0,0 +1,37 @@
+const ProtocolAction = require('../_base-action.js');
+
+/**
+ * Set the current geolocation of the mobile device.
+ *
+ * @example
+ * module.exports = {
+ *   'set geolocation to Tokyo, Japan': function (app) {
+ *     app
+ *       .appium.setGeolocation({latitude: 35.689487, longitude: 139.691706, altitude: 5});
+ *   },
+ *
+ *   'set geolocation to Tokyo, Japan with ES6 async/await': async function (app) {
+ *     await app.appium.setGeolocation({latitude: 35.689487, longitude: 139.691706});
+ *   }
+ * };
+ *
+ * @syntax .appium.setGeolocation({latitude, longitude, altitude}, [callback])
+ * @method setGeolocation
+ * @param {object} [coordinates] `latitude` and `longitude` are required; `altitude` is optional. All should be of type `number`.
+ * @param {function} [callback] Optional callback function to be called when the command finishes.
+ * @see appium.getGeolocation
+ * @api protocol.appium
+ */
+module.exports = class Session extends ProtocolAction {
+  static get isTraceable() {
+    return true;
+  }
+
+  command(coordinates = {}, callback) {
+    if (!('latitude' in coordinates && 'longitude' in coordinates)) {
+      throw new Error('Please provide both latitude and longitude while using setGeolocation.');
+    }
+
+    return this.transportActions.setDeviceGeolocation(coordinates, callback);
+  }
+};