feat: Add 'mobile: keys' extension (#2156)

Author: mykola-mokhnach

docs/execute-methods.md

@@ -1370,6 +1370,20 @@ Checks if the system on-screen keyboard is visible.
 
 `true` if the keyboard is visible
 
+### mobile: keys
+
+Send keys to the given element or to the application under test.
+This API is only supported since Xcode 15/iOS 17.
+It is not supported on tvOS.
+The API only works on iPad. On iOS calling it has no effect.
+
+#### Arguments
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+elementId | string | no | Unique identifier of the element to send the keys to. If unset then keys are sent to the current application under test. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
+keys | array | yes | Array of keys to type. Each item could either be a string, that represents a key itself (see the official documentation on XCUIElement's [typeKey:modifierFlags: method](https://developer.apple.com/documentation/xctest/xcuielement/1500604-typekey?language=objc) and on [XCUIKeyboardKey constants](https://developer.apple.com/documentation/xctest/xcuikeyboardkey?language=objc)) or a dictionary with `key` and `modifierFlags` entries, if the key should also be entered with modifiers. | ['h', 'i'] or [{key: 'h', modifierFlags: 1 << 1}, {key: 'i', modifierFlags: 1 << 2}] or ['XCUIKeyboardKeyEscape'] |
+
 ### mobile: lock
 
 Lock the device (and optionally unlock it after a certain amount of time). Only simple (e.g. without a password) locks are supported.

lib/commands/keyboard.js

@@ -34,8 +34,31 @@ export default {
       return false;
     }
   },
+
+  /**
+   * Send keys to the given element or to the application under test.
+   * This API is not supported on tvOS
+   *
+   * @since Xcode 15/iOS 17
+   * @this {import('../driver').XCUITestDriver}
+   * @param {(Key|string)[]} keys Array of keys to type.
+   * Each item could either be a string, that represents a key itself (see
+   * https://developer.apple.com/documentation/xctest/xcuielement/1500604-typekey?language=objc
+   * and https://developer.apple.com/documentation/xctest/xcuikeyboardkey?language=objc)
+   * or a dictionary, if the key should also be entered with modifiers.
+   * @param {string?} [elementId=null] uuid of the element to send keys to.
+   * If the element is not provided then the keys will be sent to the current application.
+   */
+  async mobileKeys(keys, elementId = null) {
+    const url = `/wda/element/${elementId || 0}/keyboardInput`;
+    return await this.proxyCommand(url, 'POST', { keys });
+  },
 };
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
  */
+
+/**
+ * @typedef {import('./types').KeyboardKey} Key
+ */

lib/commands/types.ts

@@ -550,3 +550,18 @@ export interface Viewport {
    */
   height: number;
 }
+
+export interface KeyboardKey {
+  /**
+   * Represents a key to type (see
+   * https://developer.apple.com/documentation/xctest/xcuielement/1500604-typekey?language=objc
+   * and https://developer.apple.com/documentation/xctest/xcuikeyboardkey?language=objc)
+   */
+  key: string;
+  /**
+   * Set of modifier flags
+   * (https://developer.apple.com/documentation/xctest/xcuikeymodifierflags?language=objc)
+   * to use when typing the key.
+   */
+  modifierFlags?: number;
+}

lib/driver.js

@@ -2032,6 +2032,7 @@ class XCUITestDriver extends BaseDriver {
   hideKeyboard = commands.keyboardExtensions.hideKeyboard;
   mobileHideKeyboard = commands.keyboardExtensions.mobileHideKeyboard;
   isKeyboardShown = commands.keyboardExtensions.isKeyboardShown;
+  mobileKeys = commands.keyboardExtensions.mobileKeys;
 
   /*--------------+
    | LOCALIZATION |

lib/execute-method-map.ts

@@ -442,6 +442,13 @@ export const executeMethodMap = {
   'mobile: calibrateWebToRealCoordinatesTranslation': {
     command: 'mobileCalibrateWebToRealCoordinatesTranslation',
   },
+  'mobile: keys': {
+    command: 'mobileKeys',
+    params: {
+      required: ['keys'],
+      optional: ['elementId'],
+    },
+  },
   'mobile: deepLink': {
     command: 'mobileDeepLink',
     params: {

package-lock.json

@@ -73,7 +73,7 @@
     "appium-ios-device": "^2.5.4",
     "appium-ios-simulator": "^5.3.3",
     "appium-remote-debugger": "^10.0.0",
-    "appium-webdriveragent": "^5.11.0",
+    "appium-webdriveragent": "^5.12.2",
     "appium-xcode": "^5.1.4",
     "async-lock": "^1.4.0",
     "asyncbox": "^2.9.4",