diff --git a/README.md b/README.md index 3b14b32e4..2458ebde1 100644 --- a/README.md +++ b/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 diff --git a/lib/commands/actions.js b/lib/commands/actions.js index a92e37aec..101415c37 100644 --- a/lib/commands/actions.js +++ b/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; diff --git a/lib/commands/general.js b/lib/commands/general.js index bf8c96cf8..88fca4530 100644 --- a/lib/commands/general.js +++ b/lib/commands/general.js @@ -139,6 +139,8 @@ extensions.executeMobile = async function (mobileCommand, opts = {}) { hideKeyboard: 'mobileHideKeyboard', isKeyboardShown: 'isKeyboardShown', + + pressKey: 'mobilePressKey', }; if (!_.has(mobileCommandsMapping, mobileCommand)) {