feat: Add mobile extension for pressKey action (#597)

README.md

@@ -1076,6 +1076,20 @@ Checks if the system on-screen keyboard is visible.
 
 `true` if the keyboard is visible
 
+### mobile: pressKey
+
+Emulates single key press on the key with the given code. Available since driver version 2.17.0
+
+#### Arguments
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+keycode | number | yes | A valid Android key code. See [KeyEvent documentation](https://developer.android.com/reference/android/view/KeyEvent) for the list of available key codes | 0x00000099 (which is KEYCODE_NUMPAD_9)
+metastate | number | no | An integer in which each bit set to 1 represents a pressed meta key. See
+[KeyEvent documentation](https://developer.android.com/reference/android/view/KeyEvent) for more details. | 0x00000010 (which is META_ALT_LEFT_ON)
+flags | number | no | Flags for the particular key event. See [KeyEvent documentation](https://developer.android.com/reference/android/view/KeyEvent) for more details. | 0x00000001 (which is FLAG_WOKE_HERE)
+isLongPress | number | no | Whether to emulate long key press. `false` by default. | true
+
 
 ## Applications Management
 

lib/commands/actions.js

@@ -35,6 +35,40 @@ commands.setOrientation = async function (orientation) {
  return await this.uiautomator2.jwproxy.command(`/orientation`, 'POST', {orientation});
 };
 
+/**
+ * @typedef {Object} PressKeyOptions
+ * @property {number} keycode A valid Android key code. See https://developer.android.com/reference/android/view/KeyEvent
+ * for the list of available key codes
+ * @property {number?} metastate An integer in which each bit set to 1 represents a pressed meta key. See
+ * https://developer.android.com/reference/android/view/KeyEvent for more details.
+ * @property {string?} flags Flags for the particular key event. See
+ * https://developer.android.com/reference/android/view/KeyEvent for more details.
+ * @property {boolean} isLongPress [false] Whether to emulate long key press
+*/
+
+/**
+ * Emulates single key press of the key with the given code.
+ *
+ * @param {PressKeyOptions} opts
+ */
+commands.mobilePressKey = async function mobilePressKey(opts = {}) {
+ const {
+ keycode,
+ metastate,
+ flags,
+ isLongPress = false,
+ } = opts;
+
+ return await this.uiautomator2.jwproxy.command(
+ `/appium/device/${isLongPress ? 'long_' : ''}press_keycode`,
+ 'POST', {
+ keycode,
+ metastate,
+ flags
+ }
+ );
+};
+
 Object.assign(extensions, commands, helpers);
 export { commands, helpers };
 export default extensions;

lib/commands/general.js

@@ -139,6 +139,8 @@ extensions.executeMobile = async function (mobileCommand, opts = {}) {
 
  hideKeyboard: 'mobileHideKeyboard',
  isKeyboardShown: 'isKeyboardShown',
+
+ pressKey: 'mobilePressKey',
  };
 
  if (!_.has(mobileCommandsMapping, mobileCommand)) {