appium-mcp 0.0.1 → 1.1.4

package/src/resources/submodules/appium-xcuitest-driver/README.md

@@ -0,0 +1,55 @@
+# appium-xcuitest-driver
+
+[![npm version](http://img.shields.io/npm/v/appium-xcuitest-driver.svg)](https://npmjs.org/package/appium-xcuitest-driver)
+[![Downloads](http://img.shields.io/npm/dm/appium-xcuitest-driver.svg)](https://npmjs.org/package/appium-xcuitest-driver)
+
+[![Release](https://github.com/appium/appium-xcuitest-driver/actions/workflows/publish.js.yml/badge.svg)](https://github.com/appium/appium-xcuitest-driver/actions/workflows/publish.js.yml)
+
+This is an [Appium](https://appium.github.io/appium) driver for automating iOS applications on iOS,
+iPadOS, and tvOS.
+
+> [!IMPORTANT]
+> Only macOS is supported as the host platform, as it requires Xcode and developer tools.
+
+> [!IMPORTANT]
+> Since major version *10.0.0*, this driver is only compatible with Appium 3. Use the `appium driver install xcuitest`
+> command to add it to your distribution.
+
+
+## Documentation
+
+The [Documentation](https://appium.github.io/appium-xcuitest-driver) is hosted separately at
+[https://appium.github.io/appium-xcuitest-driver](https://appium.github.io/appium-xcuitest-driver)
+
+## Contributing & Development
+
+Clone this project from GitHub and run:
+
+```bash
+npm install
+```
+
+To watch changes during the development:
+
+```bash
+npm run watch
+```
+
+To run unit/functional tests:
+
+```bash
+npm test # unit
+npm run e2e-test # functional
+```
+
+There are also a number of environment variables that can be used when running
+the tests locally. These include:
+
+* `REAL_DEVICE` - set to anything truthy, makes the tests use real device capabilities
+* `_FORCE_LOGS` - set to `1` to get the log output, not just spec
+* `PLATFORM_VERSION` - change the version to run the tests against (defaults to `9.3`)
+* `XCCONFIG_FILE` - specify where the xcode config file is for a real device run (if
+  blank, and running a real device test, it will search for the first file in
+  the root directory of the repo with the extension "xcconfig")
+* `UICATALOG_REAL_DEVICE` - path to the real device build of UICatalog, in case
+  the npm installed one is not built for real device

package/src/resources/submodules/appium-xcuitest-driver/docs/contributing.md

@@ -0,0 +1,45 @@
+---
+hide:
+  - navigation
+  - toc
+
+title: Contributing
+---
+
+Contributions to this project are welcome! To start off, clone it from GitHub and run:
+
+```bash
+npm install
+```
+
+To watch changes during development:
+
+```bash
+npm run watch
+```
+
+To run unit/functional tests:
+
+```bash
+npm run test # unit 
+npm run e2e-test # functional
+```
+
+To develop documentation:
+
+```bash
+npm run install-docs-deps # install the dependencies (Python packages)
+npm run dev:docs # serve the docs locally and watch for changes
+```
+
+There are also a number of environment variables that can be used when running
+the tests locally. These include:
+
+* `REAL_DEVICE` - set to anything truthy, makes the tests use real device capabilities
+* `_FORCE_LOGS` - set to `1` to get the log output, not just spec
+* `PLATFORM_VERSION` - change the version to run the tests against (defaults to `11.3`)
+* `XCCONFIG_FILE` - specify where the Xcode config file is for a real device run (if
+  blank, and running a real device test, it will search for the first file in
+  the root directory of the repo with the extension `.xcconfig`)
+* `UICATALOG_REAL_DEVICE` - path to the real device build of UICatalog, in case
+  the `npm` installed one is not built for a real device

package/src/resources/submodules/appium-xcuitest-driver/docs/endpoints-wda.md

@@ -0,0 +1,61 @@
+## WebDriverAgent JSONWP Endpoints
+
+### Session-less commands
+
+| method | endpoint                               | req params | opt params |
+| ------ | -------------------------------------- | ---------- | ---------- |
+| POST   | /wda/homescreen                        | | |
+| GET    | /source                                | | accessible |
+| GET    | /inspector                             | | |
+| GET    | /inspector.js                          | | |
+| GET    | /screenshot                            | | |
+| POST   | /session                               | desiredCapabilities
+| GET    | /status                                | | |
+| GET    | /*                                     | ** | |
+| POST   | /*                                     | ** | |
+| PUT    | /*                                     | ** | |
+| DELETE | /*                                     | ** | |
+
+
+### Session commands
+
+| method | endpoint                               | req params | opt params |
+| ------ | -------------------------------------- | ---------- | ---------- |
+| GET    | /alert/text                            | | |
+| POST   | /alert/accept                          | | |
+| POST   | /alert/dismiss                         | | |
+| POST   | /wda/deactivateApp                     | | duration |
+| POST   | /timeouts                              | * | |
+| GET    | /source                                | | accessible |
+| GET    | /element/:uuid/enabled                 | | |
+| GET    | /element/:uuid/rect                    | | |
+| GET    | /element/:uuid/attribute/:name         | | |
+| GET    | /element/:uuid/text                    | | |
+| GET    | /element/:uuid/displayed               | | |
+| GET    | /wda/element/:uuid/accessible          | | |
+| GET    | /element/:uuid/name                    | | |
+| POST   | /element/:uuid/value                   | value | |
+| POST   | /element/:uuid/click                   | | |
+| POST   | /element/:uuid/clear                   | | |
+| POST   | /wda/element/:uuid/doubleTap        | | |
+| POST   | /wda/element/:uuid/touchAndHold     | duration | |
+| POST   | /wda/element/:uuid/scroll           | | name, direction, predicateString, toVisible |
+| POST   | /uiaElement/:uuid/value                | value | |
+| POST   | /wda/element/:uuid/dragfromtoforduration | fromX, fromY, toX, toY, duration | |
+| POST   | /wda/tap/:uuid                         | x, y | |
+| POST   | /wda/keys                              | value | |
+| GET    | /window/size                           | | |
+| POST   | /element                               | using, value | |
+| POST   | /elements                              | using, value | |
+| GET    | /wda/uiaElement/:uuid/getVisibleCells  | | |
+| POST   | /element/:uuid/element                 | using, value | |
+| POST   | /element/:uuid/elements                | using, value | |
+| GET    | /orientation                           | | |
+| POST   | /orientation                           | orientation | |
+| GET    | /screenshot                            | | |
+| POST   | /wda/touch_id                | match | |
+
+
+\* implemented but intentionally not supported
+
+** not implemented handlers

package/src/resources/submodules/appium-xcuitest-driver/docs/endpoints.md

@@ -0,0 +1,98 @@
+## Appium iOS JSONWP Endpoints
+
+### Session-less commands
+
+| method | endpoint                                 | req params | opt params |
+| ------ | ---------------------------------------- | ---------- | ---------- |
+| GET    | /status                                  | | |
+| POST   | /session                                 | desiredCapabilities | requiredCapabilities |
+| GET    | /sessions                                | | |
+
+
+### Session commands
+
+| method | endpoint                                 | req params | opt params |
+| ------ | ---------------------------------------- | ---------- | ---------- |
+| GET    | /:sessionId                              | | |
+| DELETE | /:sessionId                              | | |
+| POST   | /timeouts                                | type, ms | |
+| POST   | /timeouts/async_script                   | ms | |
+| POST   | /timeouts/implicit_wait                  | ms | |
+| GET    | /window_handle                           | | |
+| GET    | /window_handles                          | | |
+| GET    | /url                                     | | |
+| POST   | /url                                     | url | |
+| POST   | /forward                                 | none | |
+| POST   | /back                                    | none | |
+| POST   | /refresh                                 | none | |
+| POST   | /execute                                 | script, args | |
+| POST   | /execute_async                           | script, args | |
+| GET    | /screenshot                              | | |
+| POST   | /frame                                   | id | |
+| POST   | /window                                  | name | |
+| DELETE | /window                                  | | |
+| GET    | /window/:windowhandle/size               | | |
+| GET    | /cookie                                  | | |
+| POST   | /cookie                                  | cookie | |
+| DELETE | /cookie                                  | | | | |
+| DELETE | /cookie/:name                            | | |
+| GET    | /source                                  | | |
+| GET    | /title                                   | | |
+| POST   | /element                                 | using, value | |
+| POST   | /elements                                | using, value | |
+| POST   | /element/active                          | none | |
+| POST   | /element/:elementId/element              | using, value | |
+| POST   | /element/:elementId/elements             | using, value | |
+| POST   | /element/:elementId/click                | none | |
+| POST   | /element/:elementId/submit               | none | |
+| GET    | /element/:elementId/text                 | none | |
+| POST   | /element/:elementId/value                | value | |
+| POST   | /keys                                    | value | |
+| GET    | /element/:elementId/name                 | | |
+| POST   | /element/:elementId/clear                | none | |
+| GET    | /element/:elementId/selected             | | |
+| GET    | /element/:elementId/enabled              | | |
+| GET    | /element/:elementId/attribute/:name      | | |
+| GET    | /element/:elementId/equals/:otherId      | | |
+| GET    | /element/:elementId/displayed            | | |
+| GET    | /element/:elementId/location             | | |
+| GET    | /element/:elementId/location_in_view     | | |
+| GET    | /element/:elementId/size                 | | |
+| GET    | /element/:elementId/css/:propertyName    | | |
+| GET    | /orientation                             | | |
+| POST   | /orientation                             | orientation | |
+| GET    | /alert_text                              | | |
+| POST   | /alert_text                              | text | |
+| POST   | /accept_alert                            | none | |
+| POST   | /dismiss_alert                           | none | |
+| POST   | /click                                   | | button |
+| GET    | /location                                | | |
+| POST   | /location                                | location | |
+| POST   | /log                                     | type | |
+| GET    | /log/types                               | | |
+| GET    | /context                                 | | |
+| POST   | /context                                 | name | |
+| GET    | /contexts                                | | |
+| POST   | /receive_async_response                  | status, value | |
+
+
+### Appium-specific commands
+
+| method | endpoint                                 | req params | opt params |
+| ------ | ---------------------------------------- | ---------- | ---------- |
+| POST   | /appium/device/shake                     | none | |
+| GET    | /appium/device/system_time               | | |
+| POST   | /appium/device/lock                      | | seconds |
+| POST   | /appium/device/rotate                    | x, y, radius, rotation, touchCount, duration | element |
+| POST   | /appium/device/remove_app                | appId or bundleId | |
+| POST   | /appium/device/hide_keyboard             | | strategy, key, keyCode, keyName |
+| POST   | /appium/device/push_file                 | path, data | |
+| POST   | /appium/device/pull_file                 | path | |
+| POST   | /appium/device/pull_folder               | path | |
+| POST   | /appium/simulator/touch_id               | match | |
+| POST   | /appium/app/launch                       | none | |
+| POST   | /appium/app/close                        | none | |
+| POST   | /appium/app/background                   | seconds | |
+| POST   | /appium/app/strings                      | | language, stringFile |
+| POST   | /appium/element/:elementId/value         | value | |
+| POST   | /appium/receive_async_response           | response | |

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/attach-to-running-wda.md

@@ -0,0 +1,43 @@
+---
+hide:
+  - toc
+
+title: Attach to a Running WebDriverAgent
+---
+
+The XCUITest driver provides the __`appium:webDriverAgentUrl`__ capability to attach to a running
+WebDriverAgent (WDA) application. This works for real devices and simulators, but the primary usage
+is for real devices.
+
+## Usage
+
+1. Start a WebDriverAgent application on a device
+2. Start an XCUITest driver session with `appium:webDriverAgentUrl` capability
+
+Please read [Manage WebDriverAgent by Yourself](./wda-custom-server.md) and
+[Real Device Configuration](../preparation/real-device-config.md) about how to prepare WDA for a
+real device.
+
+The `appium:webDriverAgentUrl` value should be the WDA URL: `http://<reachable ip address for the device>:8100`.
+If the environment has port-forward to the connected device, it can be `http://localhost:8100`.
+
+```json
+{
+  "platformName": "ios",
+  "appium:automationName": "xcuitest",
+  "appium:platformVersion": "15.5",
+  "appium:udid": "<device udid>",
+  "appium:deviceName": "iPhone",
+  "appium:webDriverAgentUrl": "http://<reachable ip address for the device>:8100"
+}
+```
+
+This method allows you to manage the WDA process by yourself. The XCUITest driver then simply
+attaches to the WDA process, which may improve the application performance.
+
+Some XCUITest driver APIs (for example,
+[mobile: calibrateWebToRealCoordinatesTranslation](../reference/execute-methods.md#mobile-calibratewebtorealcoordinatestranslation))
+might still require the port number of the remote device if it is a real device. Providing the
+`appium:webDriverAgentUrl` capability might not be sufficient to recognize the remote port number,
+in case it is different from the local one. Consider settings the `appium:wdaRemotePort` capability
+in such cases, to supply the driver with the appropriate data.

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/audio-capture.md

@@ -0,0 +1,78 @@
+---
+title: Audio Capture
+---
+
+
+Appium XCUITest driver provides a possibility to record iOS audio stream and save it to a file,
+which could be then retrieved on the client side. Apple does not provide any API to directly
+retrieve the audio stream from a Simulator or a real device, but it is possible to redirect that
+stream to the host machine, where it could be captured.
+
+* [`mobile: startAudioRecording`](../reference/execute-methods.md#mobile-startaudiorecording)
+* [`mobile: stopAudioRecording`](../reference//execute-methods.md#mobile-stopaudiorecording)
+
+## Server Requirements
+
+- The host machine must have [`ffmpeg`](https://www.ffmpeg.org/download.html) installed and added to PATH.
+  It can be installed via [`brew`](https://brew.sh/): `brew install ffmpeg`.
+- For macOS 10.15+, applications recording Microphone audio need to be explicitly granted this permission.
+  This can be done in the following settings menu:
+
+    - macOS < 13: _System Preferences -> Security & Privacy -> Privacy -> Microphone_
+    - macOS 13+: _System Settings -> Privacy & Security -> Microphone_
+
+    Ensure that either `ffmpeg` itself or the parent Appium process (e.g. Terminal) is present in that list.
+
+- As this is a potentially insecure feature, it must be explicitly allowed on the server side. See
+  [the Appium documentation on Security](https://appium.io/docs/en/latest/guides/security/) for more details.
+  The feature name is `audio_record`.
+
+## Simulator Setup
+
+The following steps are necessary to setup iOS Simulator audio capture:
+
+* Install [Soundflower](https://github.com/mattingalls/Soundflower/releases)
+* Redirect Simulator audio output to Soundflower: from the main Simulator menu, select
+  _I/O -> Audio Output -> Soundflower (2ch)_
+* In terminal, run `ffmpeg -f avfoundation -list_devices true -i ""` to get the identifier of the
+  `Soundflower (2ch)` device. This identifier prefixed with `:` will be then used as `audioInput`
+  argument to `mobile: startAudioRecording` call
+* Test that your setup works as expected. Run any audio playback in Simulator and execute the
+  following command in Terminal, replacing the `-i` argument value with the one you got from the
+  previous step:
+  ```
+  ffmpeg -t 5 -f avfoundation -i ":1" -c:a aac -b:a 128k -ac 2 -ar 44100 -y ~/Desktop/out.mp4
+  ```
+  After 5 seconds, a file named `out.mp4` should be created on your desktop, containing the recorded
+  audio stream.
+
+## Real Device Setup
+
+The following steps are necessary to setup iOS Real Device audio capture:
+
+* Connect your device to the Mac host with a cable
+* Open the _Audio MIDI Setup_ application
+    * Via Finder: _Applications -> Utilities -> Audio MIDI Setup_
+    * Via terminal: `open -a /System/Applications/Utilities/Audio\ MIDI\ Setup.app`
+* Find your phone in the list of devices there and click `Enable` next to it
+* In terminal, run `ffmpeg -f avfoundation -list_devices true -i ""` to get the identifier of your
+  device in the `AVFoundation audio devices` list. This identifier prefixed with `:` will be then
+  used as `audioInput` argument to `mobile: startAudioRecording` call
+* Test that your setup works as expected. Run any audio playback on the device and execute the
+  following command in Terminal, replacing the `-i` argument value with the value you got from the
+  previous step:
+  ```
+  ffmpeg -t 5 -f avfoundation -i ":1" -c:a aac -b:a 128k -ac 2 -ar 44100 -y ~/Desktop/out.mp4
+  ```
+  After 5 seconds, a file named `out.mp4` should be created on your desktop, containing the recorded
+  audio stream.
+
+!!! note
+
+    Apple does not allow phone calls to be redirected this way. You can only record application or system sounds.
+
+## Further Reading
+
+* <https://github.com/appium/appium-xcuitest-driver/pull/1207>
+* <https://www.macobserver.com/tips/quick-tip/iphone-audio-input-mac/>
+* <http://www.lorisware.com/blog/2012/04/28/recording-iphone-emulator-video-with-sound/>

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/capability-sets.md

@@ -0,0 +1,169 @@
+---
+title: Basic Examples of Session Capability Sets
+---
+
+This article describes necessary capabilities that must be provided in order
+to implement some common automation testing scenarios.
+It only describes very minimum sets of capabilities required to
+be included. For refined setups more of them might need to be provided. Check the
+[Capabilities](../reference/capabilities.md) article for more details
+on each option available for the fine-tuning of XCUITest driver sessions.
+
+### Application File (Real Device)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>",
+  "appium:app": "/path/to/local/package.ipa"
+}
+```
+
+`appium:app` could also be a remote app or an archive:
+
+```
+  "appium:app": "https://example.com/package.ipa"
+  "appium:app": "https://example.com/package.zip"
+```
+
+`appium:udid` could also be set to `auto` in order to select the first matched device
+connected to the host (or a single one if only one is connected):
+
+```
+  "appium:udid": "auto"
+```
+
+### Application File (Simulator)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:app": "/path/to/local/package.app"
+}
+```
+
+`appium:app` could also be an archive:
+
+```
+  "appium:app": "https://example.com/package.zip"
+  "appium:app": "/path/to/local/package.zip"
+```
+
+### Safari (Real Device)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "browserName": "Safari",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>"
+}
+```
+
+You may also provide `appium:safariInitialUrl` capability value to navigate
+to the desired page during the session startup:
+
+```
+  "appium:safariInitialUrl": "https://server.com/page"
+```
+
+### Safari (Simulator)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "browserName": "Safari",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>"
+}
+```
+
+### Pre-Installed App (Real Device)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>",
+  "appium:bundleId": "<Bundle_ID_Of_Preinstalled_App>",
+  "appium:noReset": true
+}
+```
+
+The `appium:noReset` capability is set to `true` in order to tell the driver
+the app identified by `appium:bundleId` is already preinstalled and must not be reset.
+
+### Pre-Installed App (Simulator)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:bundleId": "<Bundle_ID_Of_Preinstalled_App>",
+  "appium:noReset": true
+}
+```
+
+### Deeplink (Real Device running iOS 17+)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>",
+  "appium:initialDeeplinkUrl": "<Deeplink_Url>"
+}
+```
+
+### Deeplink (Simulator running iOS 17+)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:initialDeeplinkUrl": "<Deeplink_Url>"
+}
+```
+
+### Custom Launch (Real Device)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:platformVersion": "<iOS_Version>",
+  "appium:udid": "<Phone_UUID>",
+}
+```
+
+This will start your test at the Home screen.
+Afterwards you may use any of the application management
+methods, like [mobile: installApp](../reference//execute-methods.md#mobile-installapp)
+or [mobile: activateApp](../reference//execute-methods.md#mobile-activateapp)
+to manage the life cycle of your app or switch between contexts to
+manage web pages. Check the full list of
+[mobile: execute methods](../reference/execute-methods.md) for more details.
+
+### Custom Launch (Simulator)
+
+```json
+{
+  "platformName": "iOS",
+  "appium:automationName": "XCUITest",
+  "appium:deviceName": "<Simulator_Name>",
+  "appium:platformVersion": "<iOS_Version>"
+}
+```

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/ci-setup.md

@@ -0,0 +1,47 @@
+---
+title: Continuous Integration
+---
+
+Setting up the XCUITest driver in an automated environment brings a few challenges with it. Any scenario
+where user interaction is required must be automated or avoided altogether. For real device setup,
+you should first follow the [Real Device Configuration tutorial](../preparation/real-device-config.md).
+
+### Keychains
+
+One common scenario is a prompt asking for a keychain to be unlocked in order to sign the WebDriverAgent.
+There are multiple possible solutions for this:
+
+1. Keychains can be set to have no timeout and be unlocked manually once. This can be done using the
+   keychain access application. Sometimes keychains still lock themselves though and this approach
+   is not recommended.
+2. [It is possible to create a second keychain](../guides/troubleshooting.md#real-device-security-settings),
+   which just stores the required certificate to sign the WebDriverAgent. The issue with this
+   approach is that Codesign wants to unlock all listed keychains regardless of the specified
+   keychain, thus leading to a password prompt. This can be avoided by setting the default keychain
+   and basically hiding the login keychain at the start of the build.
+   [See this Stackoverflow article](https://stackoverflow.com/questions/16550594/jenkins-xcode-build-works-codesign-fails)
+   for how to utilize this approach. It is impractical when running other build jobs simultaneously.
+3. Stick with the existing keychains as in approach 1, but explicitly call unlock keychain before
+   **each** build. This can be done using [fastlane unlock_keychain](https://docs.fastlane.tools/actions/unlock_keychain/)
+   or by using [security unlock-keychain](https://www.unix.com/man-page/osx/1/security/) directly.
+   The password can be saved as a CI variable/secret or on the machine itself.
+
+It is recommended to go with the second or third option. The third one is the easiest and most
+reliable one to set up, at the cost of having to set the keychain password as an environment variable.
+
+### Xcode
+
+When setting up a new machine as a CI server, you are probably going to install Xcode, without
+executing it once, because you are not going to use it for development. Make sure to start Xcode at
+least once and do the initial set up and install the suggested extensions.
+
+### Linking Apple Account
+
+This only applies for real device set up. Make sure to link your 'Apple Developer Account' in the
+machine's system wide "Account Panel" when using the "Basic Automatic Configuration" described
+[here](../preparation/prov-profile-basic-auto.md).
+
+### Troubleshooting
+
+Enable the `appium:showXcodeLog` [capability](../reference/capabilities.md#webdriveragent) and
+check the Appium server output.

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/clipboard.md

@@ -0,0 +1,47 @@
+---
+hide:
+  - toc
+
+title: Get/Set Clipboard
+---
+
+Working with the clipboard on real devices has an Apple security limitation, where the
+WebDriverAgentRunner application must be in foreground in order for the action to work. Otherwise
+an empty string is always returned, or it could raise an exception like
+[this issue](https://github.com/appium/appium/issues/18730).
+
+Consider using [`mobile: activateApp`](../reference/execute-methods.md/#mobile-activateapp)
+and [`mobile: backgroundApp`](../reference/execute-methods.md/#mobile-backgroundapp) to change the
+foreground application.
+
+## Get Clipboard
+
+Applies to iOS 13+ real devices. You can also use
+[`mobile: getPasteboard`](../reference/execute-methods.md#mobile-getpasteboard) for simulators.
+
+```ruby
+# Ruby
+
+# Bring the WebDriverAgent foreground. The bundle id depends on configuration such as "appium:updatedWDABundleId" for real devices.
+driver.execute_script 'mobile: activateApp', {bundleId: 'com.facebook.WebDriverAgentRunner.xctrunner'}
+# Get the clipboard content
+driver.get_clipboard
+# Go back to the application under test
+driver.execute_script 'mobile: activateApp', {bundleId: '<bundle id of the test app>'}
+```
+
+## Set Clipboard
+
+Applies to iOS 15+ real devices. You can also use
+[`mobile: setPasteboard`](../reference/execute-methods.md#mobile-setpasteboard) for simulators.
+
+```ruby
+# Ruby
+
+# Bring the WebDriverAgent foreground. The bundle id depends on configuration such as "appium:updatedWDABundleId" for real devices.
+driver.execute_script 'mobile: activateApp', {bundleId: 'com.facebook.WebDriverAgentRunner.xctrunner'}
+# Set the clipboard content
+driver.set_clipboard(content: 'happy testing')
+# Go back to the application under test
+driver.execute_script 'mobile: activateApp', {bundleId: '<bundle id of the test app>'}
+```