feat: Add mobile: wrappers for clipboard APIs (#800)

Author: mykola-mokhnach

README.md

@@ -1340,6 +1340,26 @@ Fetches the list of supported performance data types that could be used as `data
 
 List of strings, where each item is data type name.
 
+### mobile: getClipboard
+
+Retrieves the plaintext content of the device's clipboard. Available since driver version 3.7
+
+#### 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 3.7
+
+#### 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: getPerformanceData
 
 Retrieves performance data about the given Android subsystem. The data is parsed from the output of the dumpsys utility. Available since driver version 2.24
@@ -1598,6 +1618,8 @@ Useful links:
 UiAutomator2 driver supports Appium endpoints for clipboard management:
 - Set clipboard content (`POST /appium/device/set_clipboard'`)
 - Get clipboard content (`POST /appium/device/get_clipboard`)
+- [mobile: getClipboard](#mobile-getclipboard)
+- [mobile: setClipboard](#mobile-setclipboard)
 
 Useful links:
 - https://github.com/appium/python-client/blob/master/appium/webdriver/extensions/clipboard.py

lib/commands/clipboard.js

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

lib/commands/execute.js

@@ -49,6 +49,9 @@ export function mobileCommandsMapping() {
     scheduleAction: 'mobileScheduleAction',
     getActionHistory: 'mobileGetActionHistory',
     unscheduleAction: 'mobileUnscheduleAction',
+
+    setClipboard: 'mobileSetClipboard',
+    getClipboard: 'mobileGetClipboard',
   };
 }
 

lib/commands/misc.js

@@ -40,22 +40,6 @@ export async function setOrientation(orientation) {
   );
 }
 
-/**
- * @this {AndroidUiautomator2Driver}
- * @returns {Promise<string>}
- */
-export async function getClipboard() {
-  return String(
-    (await this.adb.getApiLevel()) < 29
-      ? await this.uiautomator2.jwproxy.command(
-          '/appium/device/get_clipboard',
-          'POST',
-          {}
-        )
-      : await this.settingsApp.getClipboard()
-  );
-}
-
 /**
  * @this {AndroidUiautomator2Driver}
  * @returns {Promise<void>}

lib/commands/types.ts

@@ -471,3 +471,18 @@ export interface ActionResult {
 export interface ActionArgs {
   name: string;
 }
+
+export interface SetClipboardOpts {
+  /**
+   * Base64-encoded clipboard payload
+   */
+  content: string;
+  /**
+   * Only a single content type is supported, which is 'plaintext'
+   */
+  contentType?: 'plaintext';
+  /**
+   * Optinal label to identify the current clipboard payload
+   */
+  label?: string;
+}

lib/driver.ts

@@ -61,6 +61,12 @@ import {
 import {
   mobileGetBatteryInfo,
 } from './commands/battery';
+import {
+  getClipboard,
+  mobileGetClipboard,
+  setClipboard,
+  mobileSetClipboard,
+} from './commands/clipboard';
 import {
   active,
   getAttribute,
@@ -111,7 +117,6 @@ import {
   getPageSource,
   getOrientation,
   setOrientation,
-  getClipboard,
   openNotifications,
   suspendChromedriverProxy,
   mobileGetDeviceInfo,
@@ -1054,11 +1059,15 @@ class AndroidUiautomator2Driver
   getPageSource = getPageSource;
   getOrientation = getOrientation;
   setOrientation = setOrientation;
-  getClipboard = getClipboard;
   openNotifications = openNotifications;
   suspendChromedriverProxy = suspendChromedriverProxy as any;
   mobileGetDeviceInfo = mobileGetDeviceInfo;
 
+  getClipboard = getClipboard;
+  mobileGetClipboard = mobileGetClipboard;
+  setClipboard = setClipboard;
+  mobileSetClipboard = mobileSetClipboard;
+
   setUrl = setUrl;
   mobileDeepLink = mobileDeepLink;
   back = back;