feat: Add mobile: wrappers to clipboard APIs (#1018)

README.md

@@ -1262,6 +1262,26 @@ formFields | Map<string, string> or Array<Pair> | no | Additional fo
 
 Base64-encoded content of the recorded media file if `remotePath` argument is falsy or an empty string.
 
+### mobile: getClipboard
+
+Retrieves the plaintext content of the device's clipboard. Available since driver version 2.44
+
+#### Returned Result
+
+Base64-encoded content of the clipboard or an empty string if the clipboard is empty.
+
+### mobile: setClipboard
+
+Allows to set the plain text content of the device's clipboard. Available since driver version 2.44
+
+#### Arguments
+
+Name | Type | Required | Description | Example
+--- | --- | --- | --- | ---
+content | string | yes | Base64-encoded clipboard payload. | YXBwaXVt
+contentType | string | no | The only supported and the default value is `plaintext` | plaintext
+lable | string | no | Optinal label to identify the current clipboard payload. | yolo
+
 ### mobile: hideKeyboard
 
 Tries to hide the on-screen keyboard. Throws an exception if the keyboard cannot be hidden.

lib/commands/clipboard.js

@@ -0,0 +1,41 @@
+/**
+ * @this {import('../driver').EspressoDriver}
+ * @returns {Promise<string>} Base64-encoded content of the clipboard
+ * or an empty string if the clipboard is empty.
+ */
+export async function getClipboard () {
+  return /** @type {string} */ ((await this.adb.getApiLevel() < 29)
+    ? (await this.espresso.jwproxy.command('/appium/device/get_clipboard', 'POST', {}))
+    : (await this.settingsApp.getClipboard()));
+}
+
+/**
+ * @typedef {Object} SetClipboardOptions
+ * @property {string} content Base64-encoded clipboard payload
+ * @property {'plaintext'} [contentType] Only a single
+ * content type is supported, which is 'plaintext'
+ * @property {string} [label] Optinal label to identify the current
+ * clipboard payload
+ */
+
+/**
+ * @this {EspressoDriver}
+ * @param {SetClipboardOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function mobileSetClipboard(opts) {
+  const {
+    content,
+    contentType,
+    label,
+  } = opts;
+  await this.espresso.jwproxy.command(
+    '/appium/device/set_clipboard',
+    'POST',
+    {content, contentType, label}
+  );
+}
+
+/**
+ * @typedef {import('../driver').EspressoDriver} EspressoDriver
+ */

lib/commands/execute.js

@@ -40,6 +40,9 @@ export function mobileCommandsMapping() {
     waitForUIThread: 'mobileWaitForUIThread',
 
     pressKey: 'mobilePressKey',
+
+    setClipboard: 'mobileSetClipboard',
+    getClipboard: 'mobileGetClipboard',
   };
 }
 

lib/commands/misc.js

@@ -2,15 +2,6 @@ import { util } from 'appium/support';
 import { errors } from 'appium/driver';
 import { requireOptions } from '../utils';
 
-/**
- * @this {import('../driver').EspressoDriver}
- */
-export async function getClipboard () {
-  return (await this.adb.getApiLevel() < 29)
-    ? (await this.espresso.jwproxy.command('/appium/device/get_clipboard', 'POST', {}))
-    : (await this.settingsApp.getClipboard());
-}
-
 /**
  * @typedef {Object} PressKeyOptions
  * @property {number} [keycode] A valid Android key code. See https://developer.android.com/reference/android/view/KeyEvent

lib/driver.ts

@@ -24,6 +24,7 @@ import * as servicesCmds from './commands/services';
 import * as screenshotCmds from './commands/screenshot';
 import * as idlingResourcesCmds from './commands/idling-resources';
 import * as actionsCmds from './commands/actions';
+import * as clipboardCmds from './commands/clipboard';
 import { DEFAULT_ADB_PORT } from 'appium-adb';
 import { AndroidDriver, utils } from 'appium-android-driver';
 import { SETTINGS_HELPER_ID } from 'io.appium.settings';
@@ -726,7 +727,6 @@ export class EspressoDriver extends AndroidDriver implements ExternalDriver<
   mobileClickAction = elementCmds.mobileClickAction;
   mobileDismissAutofill = elementCmds.mobileDismissAutofill;
 
-  getClipboard = miscCmds.getClipboard;
   mobilePressKey = miscCmds.mobilePressKey;
   mobileGetDeviceInfo = miscCmds.mobileGetDeviceInfo;
   mobileIsToastVisible = miscCmds.mobileIsToastVisible;
@@ -737,6 +737,10 @@ export class EspressoDriver extends AndroidDriver implements ExternalDriver<
   updateSettings = miscCmds.updateSettings;
   getSettings = miscCmds.getSettings;
 
+  getClipboard = clipboardCmds.getClipboard;
+  mobileGetClipbard = clipboardCmds.getClipboard;
+  mobileSetClipbard = clipboardCmds.mobileSetClipboard;
+
   mobileStartService = servicesCmds.mobileStartService;
   mobileStopService = servicesCmds.mobileStopService;