### Java Example for WDA Startup with iproxy

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/wda-custom-server

This Java class illustrates the main implementation details for starting the WebDriverAgent (WDA) using `iproxy`. It includes configurations for signing WDA for real device tests and setting up necessary paths and parameters for `iproxy` and `xcodebuild`.

```java
public class WDAServer {
    private static final Logger log = ZLogger.getLog(WDAServer.class.getSimpleName());

    private static final int MAX_REAL_DEVICE_RESTART_RETRIES = 1;
    private static final Timedelta REAL_DEVICE_RUNNING_TIMEOUT = Timedelta.ofMinutes(4);
    private static final Timedelta RESTART_TIMEOUT = Timedelta.ofMinutes(1);

    // These settings are needed to properly sign WDA for real device tests
    // See https://github.com/appium/appium-xcuitest-driver for more details
    private static final File KEYCHAIN = new File(String.format("%s/%s",
            System.getProperty("user.home"), "/Library/Keychains/MyKeychain.keychain"));
    private static final String KEYCHAIN_PASSWORD = "******";

    private static final File IPROXY_EXECUTABLE = new File("/usr/local/bin/iproxy");
    private static final File XCODEBUILD_EXECUTABLE = new File("/usr/bin/xcodebuild");
    private static final File WDA_PROJECT =
            new File("~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent"
                    + "/WebDriverAgent.xcodeproj");
    private static final String WDA_SCHEME = "WebDriverAgentRunner";
    private static final String WDA_CONFIGURATION = "Debug";
    private static final File XCODEBUILD_LOG = new File("/usr/local/var/log/appium/build.log");
    private static final File IPROXY_LOG = new File("/usr/local/var/log/appium/iproxy.log");

    private static final int PORT = 8100;
    public static final String SERVER_URL = String.format("http://127.0.0.1:%d", PORT);

    private static final String[] IPROXY_CMDLINE = new String[]{
            IPROXY_EXECUTABLE.getAbsolutePath(),
            Integer.toString(PORT),
            Integer.toString(PORT),
            String.format("> %s 2>&1 &", IPROXY_LOG.getAbsolutePath())
    };

    private static WDAServer instance = null;
    private final boolean isRealDevice;
    private final String deviceId;
    private final String platformVersion;
    private int failedRestartRetriesCount = 0;

    private WDAServer() {
        try {
            this.isRealDevice = !getIsSimulatorFromConfig(getClass());
            final String udid;
            if (isRealDevice) {
                udid = IOSRealDeviceHelpers.getUDID();
            } else {
                udid = IOSSimulatorHelpers.getId();
            }
            this.deviceId = udid;
            this.platformVersion = getPlatformVersionFromConfig(getClass());
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
        ensureToolsExistence();
        ensureParentDirExistence();
    }

    public synchronized static WDAServer getInstance() {
        if (instance == null) {
            instance = new WDAServer();
        }
        return instance;
    }

    private boolean waitUntilIsRunning(Timedelta timeout) throws Exception {
        final URL status = new URL(SERVER_URL + "/status");
        try {
            if (timeout.asSeconds() > 5) {
                log.debug(String.format("Waiting max %s until WDA server starts responding...", timeout));
            }
            new UrlChecker().waitUntilAvailable(timeout.asMillis(), TimeUnit.MILLISECONDS, status);
            return true;
        } catch (UrlChecker.TimeoutException e) {
            return false;
        }
    }

    private static void ensureParentDirExistence() {
        if (!XCODEBUILD_LOG.getParentFile().exists()) {
            if (!XCODEBUILD_LOG.getParentFile().mkdirs()) {
                throw new IllegalStateException(String.format(
                        "The script has failed to create '%s' folder for Appium logs. " +
                                "Please make sure your account has correct access permissions on the parent folder(s)",
                        XCODEBUILD_LOG.getParentFile().getAbsolutePath()));
            }
        }
    }

    private void ensureToolsExistence() {
        if (isRealDevice && !IPROXY_EXECUTABLE.exists()) {

```

--------------------------------

### Start Appium Server

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/run-preinstalled-wda

Start the Appium server to enable session initiation.

```bash
appium

```

--------------------------------

### Start Recording Screen

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/commands

Starts recording the device screen. This functionality is available on iOS Simulator (Xcode 9+) and real devices (iOS 11+). Requires `ffmpeg` to be installed.

```APIDOC
## POST /session/:sessionId/appium/start_recording_screen

### Description
Start recording the device screen. This functionality is available in the iOS Simulator since Xcode 9, and in real devices since iOS 11.
Screen activity is recorded to an MPEG-4 file. Note that audio is not recorded with the video file. If the screen recording has already been started, this command will force stop it and start a new recording. The previously recorded video file will also be deleted.

Info
This command requires the `ffmpeg` utility to be installed (`brew install ffmpeg`)

**Throws**
If the screen recording has failed to start.

### Method
POST

### Endpoint
/session/:sessionId/appium/start_recording_screen

### Parameters
#### Query Parameters
- **options** (any) - Optional - Additional options for recording.

### Response
#### Success Response (200)
- **string** - Base64-encoded content of the recorded media file if any screen recording is currently running, or an empty string.

### Request Example
```json
{
  "options": {
    "maxLength": 300,
    "videoQuality": "medium"
  }
}
```

### Response Example
```json
"SGVsbG8gV29ybGQh"
```
```

--------------------------------

### Start tvOS Session (Wired)

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/tvos

Configuration for starting an Appium session with a wired tvOS device. Follow the Real Device Setup document before initiating the session.

```json
{
    "platformName": "tvOS",
    "appium:automationName": "XCUITest",
    "appium:udid": "<apple-tv-udid>",
    "appium:platformVersion": "<tvos-version",
    ...
}
```

--------------------------------

### Install Project Dependencies

Source: https://appium.github.io/appium-xcuitest-driver/latest/contributing

Run this command after cloning the repository to install all necessary project dependencies.

```bash
npm install
```

--------------------------------

### Check WDA Prerequisites

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/wda-custom-server

Ensures that essential tools like iproxy and xcodebuild are installed and the WDA project exists before attempting to start the server.

```java
if (!IPROXY_EXECUTABLE.exists()) {
            throw new IllegalStateException(String.format("%s tool is expected to be installed (`npm install -g iproxy`)",
                    IPROXY_EXECUTABLE.getAbsolutePath()));
        }
        if (!XCODEBUILD_EXECUTABLE.exists()) {
            throw new IllegalStateException(String.format("xcodebuild tool is not detected on the current system at %s",
                    XCODEBUILD_EXECUTABLE.getAbsolutePath()));
        }
        if (!WDA_PROJECT.exists()) {
            throw new IllegalStateException(String.format("WDA project is expected to exist at %s",
                    WDA_PROJECT.getAbsolutePath()));
        }
```

--------------------------------

### Install ffmpeg using Homebrew

Source: https://appium.github.io/appium-xcuitest-driver/latest/getting-started/system-requirements

Install ffmpeg for test video recording using the Homebrew package manager.

```bash
brew install ffmpeg
```

--------------------------------

### Develop Documentation Locally

Source: https://appium.github.io/appium-xcuitest-driver/latest/contributing

Install documentation dependencies and serve the documentation locally. Changes will be reflected as you develop.

```bash
npm run install-docs-deps # install the dependencies (Python packages)
```

```bash
npm run dev:docs # serve the docs locally and watch for changes
```

--------------------------------

### Launch Appium Server

Source: https://appium.github.io/appium-xcuitest-driver/latest/getting-started/installation

Launch the Appium server to verify the installation. Check server logs for confirmation.

```bash
appium

```

--------------------------------

### Install and Launch WDA from Prebuilt Path

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/run-preinstalled-wda

Configure the driver to install and launch a WDA application from a specified prebuilt path. This is necessary because test bundles cannot be versioned like regular applications and must be reinstalled for each session. Ensure the test bundle is properly signed for real devices.

```ruby
capabilities: {
  "platformName": "ios",
  "appium:automationName": "xcuitest",
  "appium:udid": "<udid>",
  "appium:usePreinstalledWDA": true,
  "appium:prebuiltWDAPath": "/path/to/Library/Developer/Xcode/DerivedData/WebDriverAgent-<random string>/Build/Products/Debug-iphoneos/WebDriverAgentRunner-Runner.app"
}
@core = Appium::Core.for capabilities: capabilities
driver = @core.start_driver
# do something
driver.quit
```

--------------------------------

### Start Screen Recording with Options

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Starts screen recording using ffmpeg and WebDriverAgent. Requires ffmpeg on PATH. Audio is not recorded. Supports various video encoding and scaling options.

```javascript
await driver.execute('mobile: startScreenRecording', {
  timeLimit: 120,
  videoType: 'libx264',
  videoFps: 10,
  videoScale: '720:1280',
  pixelFormat: 'yuv420p',
});
```

--------------------------------

### Download tvOS WDA for Simulator

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/scripts

Example of downloading the tvOS version of the WDA app into an absolute path.

```bash
appium driver run xcuitest download-wda-sim -- --platform=tvos --outdir=/path/to/dir
```

--------------------------------

### Setup WebDriverAgent Directory

Source: https://appium.github.io/appium-xcuitest-driver/latest/getting-started/provisioning-profile/full-manual-config

Run this command in the terminal within the WebDriverAgent directory to create the necessary Resources/WebDriverAgent.bundle directory.

```bash
mkdir -p Resources/WebDriverAgent.bundle

```

--------------------------------

### Open Audio MIDI Setup Application

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/audio-capture

This command opens the Audio MIDI Setup application on macOS, which is used to configure audio input/output for real devices. This application is necessary for enabling and identifying your connected iOS device for audio capture.

```bash
open -a /System/Applications/Utilities/Audio\ MIDI\ Setup.app
```

--------------------------------

### Download iOS WDA for Simulator

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/scripts

Example of downloading the iOS version of the WDA app into a specified subdirectory.

```bash
appium driver run xcuitest download-wda-sim -- --platform=ios --outdir=wda
```

--------------------------------

### Install Local APP on Simulator

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/capability-sets

Use this capability set to install a local APP file on an iOS simulator.

```json
{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:deviceName": "<Simulator_Name>",
  "appium:platformVersion": "<iOS_Version>",
  "appium:app": "/path/to/local/package.app"
}
```

--------------------------------

### Press Guide Button (tvOS)

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Emulates a press action on the guide button for tvOS. Supported on Xcode 15+.

```javascript
await driver.execute("mobile: pressButton", {"name": "guide"});
```

--------------------------------

### Query App State

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Queries the state of an installed application. An exception is thrown if the app is not installed.

```bash
# Example usage for queryAppState (actual syntax depends on the client library)
driver.executeScript("mobile:queryAppState", {"bundleId": "com.mycompany.myapp"})
```

--------------------------------

### Install Appium XCUITest Driver

Source: https://appium.github.io/appium-xcuitest-driver/latest/getting-started/installation

Use this command to install the latest version of the XCUITest driver. Ensure prerequisites are met.

```bash
appium driver install xcuitest

```

--------------------------------

### List Installed Apps

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Lists applications installed on the device. This command is not supported for simulators. It can filter by application type and return specific attributes.

```bash
# Example usage for listApps with specific attributes (actual syntax depends on the client library)
driver.executeScript("mobile:listApps", {"returnAttributes": ["CFBundleIdentifier", "CFBundleName", "CFBundleVersion"], "applicationType": "User"})
```

--------------------------------

### Start tvOS Session (Wireless)

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/tvos

Configuration for starting an Appium session with a wireless tvOS device. Ensure the device is discoverable and meets real device requirements.

```json
{
    "platformName": "tvOS",
    "appium:automationName": "XCUITest",
    "appium:udid": "<apple-tv-udid>",
    "appium:platformVersion": "<tvos-version>",
    ...
}
```

--------------------------------

### Install ffmpeg on macOS

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/audio-capture

Use Homebrew to install ffmpeg on your macOS machine. This is a prerequisite for audio capture.

```bash
brew install ffmpeg
```

--------------------------------

### Install Local IPA on Real Device

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/capability-sets

Use this capability set to install a local IPA file on a real iOS device.

```json
{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:platformVersion": "<iOS_Version>",
  "appium:udid": "<Phone_UUID>",
  "appium:app": "/path/to/local/package.ipa"
}
```

--------------------------------

### Execute Script - Python

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of executing a script with custom arguments in Python. Arguments are provided as a dictionary.

```python
result = driver.execute_script('mobile: <methodName>', {
    'arg1': 'value1',
    'arg2': 'value2',
})

```

--------------------------------

### Execute Script - C#

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of executing a script with custom arguments in C#. Arguments are provided as a Dictionary.

```csharp
object result = driver.ExecuteScript("mobile: <methodName>", new Dictionary<string, object>() {
    {"arg1", "value1"},
    {"arg2", "value2"}
}));

```

--------------------------------

### Execute Script - Ruby

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of executing a script with custom arguments in Ruby. Arguments are passed as a hash.

```ruby
result = @driver.execute_script 'mobile: <methodName>', {
    arg1: 'value1',
    arg2: 'value2',
}

```

--------------------------------

### Get Pasteboard - C#

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of getting the Simulator's pasteboard content using 'mobile: getPasteboard' in C#. Does not work on real devices.

```csharp
object result = driver.ExecuteScript("mobile: getPasteboard", new Dictionary<string, object>() {
    {"encoding", "ascii"}
});

```

--------------------------------

### Get Pasteboard - Ruby

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of getting the Simulator's pasteboard content using 'mobile: getPasteboard' in Ruby. Does not work on real devices.

```ruby
result = @driver.execute_script 'mobile: getPasteboard', {
    encoding: 'ascii'
}

```

--------------------------------

### Get Pasteboard - Python

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of getting the Simulator's pasteboard content using 'mobile: getPasteboard' in Python. Does not work on real devices.

```python
result = driver.execute_script('mobile: getPasteboard', {
    'encoding': 'ascii'
})

```

--------------------------------

### Get Pasteboard - Java

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of getting the Simulator's pasteboard content using 'mobile: getPasteboard' in Java. Does not work on real devices.

```java
var result = driver.executeScript("mobile: getPasteboard", Map.ofEntries(
    Map.entry("encoding", "ascii")
));

```

--------------------------------

### Get Pasteboard - JavaScript (WebdriverIO)

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of getting the Simulator's pasteboard content using 'mobile: getPasteboard' in JavaScript. Does not work on real devices.

```javascript
const result = await driver.executeScript('mobile: getPasteboard', [{
    encoding: "ascii"
}]);

```

--------------------------------

### Get Source - C#

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of retrieving the source tree of the current page using 'mobile: source' in C#.

```csharp
object result = driver.ExecuteScript("mobile: source");

```

--------------------------------

### Get Source - Ruby

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of retrieving the source tree of the current page using 'mobile: source' in Ruby.

```ruby
result = @driver.execute_script 'mobile: source'

```

--------------------------------

### Get Source - Python

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of retrieving the source tree of the current page using 'mobile: source' in Python.

```python
result = driver.execute_script('mobile: source')

```

--------------------------------

### Get Source - Java

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of retrieving the source tree of the current page using 'mobile: source' in Java.

```java
var result = driver.executeScript("mobile: source");

```

--------------------------------

### Get Source - JavaScript (WebdriverIO)

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Example of retrieving the source tree of the current page using 'mobile: source' in JavaScript.

```javascript
const result = await driver.executeScript('mobile: source');

```

--------------------------------

### mobile: clearApp

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Deletes data files from the data container of an installed app, allowing it to start from a clean state. This API only works on simulators.

```APIDOC
## mobile: clearApp

### Description
Deletes data files from the data container of an installed app, so it could start from the clean state next time it is launched. The destination app will be terminated if it is running when this API is invoked. This API only works on simulators.

### Arguments
#### Path Parameters
- **bundleId** (string) - Required - The bundle identifier of the application to be cleared

### Returned Result
`true` if at least one item has been successfully deleted from the app data container.
```

--------------------------------

### Switching Between Native and Web View Contexts in Java

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/hybrid

Demonstrates how to get available contexts, switch to a web view context, interact with a web element, and switch back to the native context. Ensure the web view is inspectable and accessible.

```java
// java
// assuming we have a set of capabilities
driver = new AppiumDriver(new URL("http://127.0.0.1:4723/"), options);

Set<String> contextNames = driver.getContextHandles();
for (String contextName : contextNames) {
    System.out.println(contextName); //prints out something like NATIVE_APP \n WEBVIEW_1
}
driver.context(contextNames.toArray()[1]); // set context to WEBVIEW_1

//do some web testing
String myText = driver.findElement(By.cssSelector(".green_button")).click();

driver.context("NATIVE_APP");

// do more native testing if we want

driver.quit();

```

--------------------------------

### mobile: getPermission

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Gets application permission state on Simulator. This method requires WIX applesimutils to be installed on the host where Appium server is running.

```APIDOC
## mobile: getPermission

### Description
Gets application permission state on Simulator. This method requires WIX applesimutils to be installed on the host where Appium server is running.

### Arguments
#### Required
* **bundleId** (string) - The bundle identifier of the destination app.
* **service** (string) - One of available service names. The following services are supported: `calendar`, `camera`, `contacts`, `homekit`, `microphone`, `photos`, `reminders`, `medialibrary`, `motion`, `health`, `siri`, `speech`.

### Example
```json
{
  "bundleId": "com.mycompany.myapp",
  "service": "camera"
}
```
```

--------------------------------

### Display Help for Download WDA Script

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/run-prebuilt-wda

Run this command to view all available options, flags, and defaults for the `appium driver run xcuitest download-wda` script.

```bash
appium driver run xcuitest download-wda -- --help

```

--------------------------------

### Verify XCUITest Driver Requirements with Appium Doctor

Source: https://appium.github.io/appium-xcuitest-driver/latest/getting-started/system-requirements

Use this command to check if your current setup meets the requirements for the XCUITest driver. This is useful if you already have the driver installed.

```bash
appium driver doctor xcuitest

```

--------------------------------

### Execute Remote Button Press (Python)

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/tvos

Example of pressing remote buttons like 'Home' or 'Up' using the `mobile: pressButton` extension in Python. The `switch_to.active_element` can be used to get the currently focused element.

```python
element = driver.find_element_by_accessibility_id('element on the app')
element.get_attribute('focused')
element.click()
driver.query_app_state('test.package.name')
driver.execute_script('mobile: pressButton', { 'name': 'Home' })
driver.execute_script('mobile: pressButton', { 'name': 'Up' })
element = driver.switch_to.active_element
element.get_attribute('label')
```

--------------------------------

### mobile: startPerfRecord

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Starts performance profiling for the device under test using xctrace or instruments. It is possible to record multiple profiles simultaneously.

```APIDOC
## mobile: startPerfRecord

### Description
Starts performance profiling for the device under test. Relaxing security is mandatory for simulators. It can always work for real devices. Since XCode 12 the method tries to use `xctrace` tool to record performance stats. The `instruments` developer utility is used as a fallback for this purpose if `xctrace` is not available. It is possible to record multiple profiles at the same time.

### Arguments
#### Query Parameters
- **timeout** (number) - Optional - The maximum count of milliseconds to record the profiling information. `300000`ms by default (5 minutes)
- **profileName** (string) - Optional - The name of existing performance profile to apply. `Activity Monitor` by default.
- **pid** (string or number) - Optional - The ID of the process to measure the performance for. Set it to `current` in order to measure the performance of the process, which belongs to the currently active application. All processes running on the device are measured if pid is unset (the default setting).
```

--------------------------------

### Download Prebuilt WDA for Simulator

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/run-prebuilt-wda

This command downloads a prebuilt WebDriverAgent package suitable for simulator use. Specify the output directory, kind (simulator), and platform.

```bash
appium driver run xcuitest download-wda -- --outdir=/path/to/target/directory --kind=sim --platform=ios

```

--------------------------------

### Launch App with Arguments (Ruby)

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Launches an application with specified bundle ID and custom arguments for language and locale. Ensure the app is terminated before launching with arguments if it's already running.

```ruby
driver.execute_script "mobile:launchApp", {
  "bundleId": "com.apple.Preferences",
  "arguments": ["-AppleLanguages", "(ja)", "-AppleLocale", "ja_JP"]
}
```

--------------------------------

### Download WDA for Simulator

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/scripts

Download the WebDriverAgent (WDA) application bundle for simulator use. Specify the target platform (ios or tvos) and the output directory.

```bash
appium driver run xcuitest download-wda-sim -- --outdir=<outdir> --platform=<platform>
```

--------------------------------

### Launch Appium with Device Control Flag

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/tvos

Start the Appium server with the `APPIUM_XCUITEST_PREFER_DEVICECTL` environment variable set to 1. This is required for wireless automation on tvOS 17 and later when not using the Remote XPC approach.

```bash
APPIUM_XCUITEST_PREFER_DEVICECTL=1 appium
```

--------------------------------

### GET /session/:sessionId/window/:windowhandle/size

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/commands

Deprecated: Gets the window size. Use `getElementRect` instead.

```APIDOC
## GET /session/:sessionId/window/:windowhandle/size

### Description
Deprecated: Gets the window size. Use `getElementRect` instead.

### Method
GET

### Endpoint
/session/:sessionId/window/:windowhandle/size

### Response
#### Success Response (200)
- **any** - The window size, typically an object with `width` and `height` properties.

### Response Example
```json
{
  "width": 375,
  "height": 667
}
```
```

--------------------------------

### Launch App with Arguments (C#)

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Launches an application with specified bundle ID and custom arguments for language and locale. Ensure the app is terminated before launching with arguments if it's already running.

```csharp
driver.ExecuteScript("mobile:launchApp", new Dictionary<string, object>() {
    {"bundleId", "com.apple.Preferences"},
    {"arguments", new List<string>() { "-AppleLanguages", "(ja)", "-AppleLocale", "ja_JP" }}
});
```

--------------------------------

### Install Certificate

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Installs a custom certificate onto the device. Requires `appium-ios-remotexpc` on real devices running iOS/tvOS 18+. For simulators predating Xcode 11.4, it wraps the certificate in a .mobileconfig and uses WebDriverAgent to drive the installation.

```javascript
await driver.execute("mobile: installCertificate", {
  content: "a23234...",
  commonName: "com.myorg",
  isRoot: false
});
```

--------------------------------

### mobile: isAppInstalled

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Checks if a specified application is installed on the device under test. Offloaded applications are considered not installed.

```APIDOC
## mobile: isAppInstalled

### Description
Checks whether the given application is installed on the device under test. Offloaded applications are handled as not installed.

### Arguments
#### Path Parameters
- **bundleId** (string) - Required - The bundle identifier of the application to be checked

### Returned Result
Either `true` or `false`
```

--------------------------------

### Launch App with Arguments (Python)

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Launches an application with specified bundle ID and custom arguments for language and locale. Ensure the app is terminated before launching with arguments if it's already running.

```python
driver.execute_script("mobile:launchApp", {
  "bundleId": "com.apple.Preferences",
  "arguments": ["-AppleLanguages", "(ja)", "-AppleLocale", "ja_JP"]
})
```

--------------------------------

### Launch App with Arguments (Java)

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Launches an application with specified bundle ID and custom arguments for language and locale. Ensure the app is terminated before launching with arguments if it's already running.

```java
driver.executeScript("mobile:launchApp", Map.of(
    "bundleId", "com.apple.Preferences",
    "arguments", Arrays.asList("-AppleLanguages", "(ja)", "-AppleLocale", "ja_JP")
));
```

--------------------------------

### GET /session/:sessionId/element/:elementId/location

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/commands

Deprecated: Gets the position of an element on the screen. Use `getElementRect` instead.

```APIDOC
## GET /session/:sessionId/element/:elementId/location

### Description
Deprecated: Gets the position of an element on the screen. Use `getElementRect` instead.

### Method
GET

### Endpoint
/session/:sessionId/element/:elementId/location

### Response
#### Success Response (200)
- **Position** (object) - The position of the element, containing `x`, `y`, `width`, and `height` properties.

### Response Example
```json
{
  "x": 100,
  "y": 200,
  "width": 50,
  "height": 30
}
```
```

--------------------------------

### mobile: launchApp

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Executes the given application on the device under test. It can accept arguments and environment variables to start the application with specific configurations. If the application is already running, it will be activated.

```APIDOC
## mobile: launchApp

### Description
Executes the given application on the device under test. If the application is already running then it would be activated. If the application is not installed or cannot be launched then an exception is thrown. It accepts `arguments` and `environment` to start an application with them.

### Method
executeScript

### Endpoint
mobile:launchApp

### Parameters
#### Arguments
- **bundleId** (string) - Required - The bundle identifier of the application to be launched
- **arguments** (string array) - Optional - One or more command line arguments for the app. If the app is already running then this argument is ignored.
- **environment** (dict) - Optional - Environment variables mapping for the app. If the app is already running then this argument is ignored.

### Request Example
```json
{
  "bundleId": "com.apple.Preferences",
  "arguments": ["-AppleLanguages", "(ja)", "-AppleLocale", "ja_JP"]
}
```
```

--------------------------------

### Install Remote Archive on Simulator

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/capability-sets

Use this capability set to install a remote ZIP archive on an iOS simulator.

```json
  "appium:app": "https://example.com/package.zip"
  "appium:app": "/path/to/local/package.zip"
```

--------------------------------

### Run image-mounter without subcommand

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/scripts

Execute the image-mounter script without any subcommand to display help text.

```bash
appium driver run xcuitest image-mounter
```

--------------------------------

### Launch Pre-Installed App on Simulator

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/capability-sets

Use this capability set to launch a pre-installed app on an iOS simulator without resetting its state.

```json
{
  "platformName": "iOS",
  "appium:automationName": "XCUITest",
  "appium:deviceName": "<Simulator_Name>",
  "appium:platformVersion": "<iOS_Version>",
  "appium:bundleId": "<Bundle_ID_Of_Preinstalled_App>",
  "appium:noReset": true
}
```

--------------------------------

### Appium Capabilities for Prebuilt WDA using useXctestrunFile

Source: https://appium.github.io/appium-xcuitest-driver/latest/guides/run-prebuilt-wda

Use these capabilities to skip the `build-for-testing` command and execute only the `test-without-building` command. This requires WDA files to be pre-built using `xcodebuild`.

```json
{
  "platformName": "ios",
  "appium:automationName": "xcuitest",
  "appium:platformVersion": "18.4",
  "appium:deviceName": "iPhone 16",
  "appium:useXctestrunFile": true,
  "appium:bootstrapPath": "/path/to/wda_build/Build/Products"
}
```

--------------------------------

### mobile: installApp

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Installs a given application onto the device under test. Requires the application to be built for the correct architecture and properly signed. Supports an optional timeout and version checking.

```APIDOC
## mobile: installApp

### Description
Installs the given application to the device under test. Make sure the application is built for a correct architecture and is signed with a proper developer signature (for real devices) prior to install it.

### Arguments
#### Path Parameters
- **app** (string) - Required - See the description of the `appium:app` capability
#### Query Parameters
- **timeoutMs** (number) - Optional - The maximum time to wait until app install is finished in milliseconds on real devices. If not provided then the value of `appium:appPushTimeout` capability is used. If the capability is not provided then equals to 240000ms
- **checkVersion** (bool) - Optional - If set to `true`, it will make xcuitest driver to verify whether the app version currently installed on the device under test is older than the one, which is provided as `app` value. No app install is going to happen if the candidate app has the same or older version number than the already installed copy of it. The version number used for comparison must be provided as CFBundleVersion Semantic Versioning-compatible value in the application's `Info.plist`. No validation is performed and the `app` is installed if `checkVersion` was not provided or `false`, which is default behavior.
```

--------------------------------

### mobile: queryAppState

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Queries the state of an installed application from the device under test. An exception will be thrown if the app with the given identifier is not installed.

```APIDOC
## mobile: queryAppState

### Description
Queries the state of an installed application from the device under test. An exception will be thrown if the app with given identifier is not installed.

### Method
executeScript

### Endpoint
mobile:queryAppState

### Parameters
#### Arguments
- **bundleId** (string) - Required - The bundle identifier of the application to be queried

### Returned Result
An integer number is returned, which encodes the application state. Possible values are described in XCUIApplicationState XCTest documentation topic.
```

--------------------------------

### GET /session/:sessionId/element/:elementId/location_in_view

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/commands

Deprecated: Alias for `getLocation`. Gets the position of an element on the screen. Use `getElementRect` instead.

```APIDOC
## GET /session/:sessionId/element/:elementId/location_in_view

### Description
Deprecated: Alias for `getLocation`. Gets the position of an element on the screen. Use `getElementRect` instead.

### Method
GET

### Endpoint
/session/:sessionId/element/:elementId/location_in_view

### Response
#### Success Response (200)
- **Position** (object) - The position of the element, containing `x`, `y`, `width`, and `height` properties.

### Response Example
```json
{
  "x": 100,
  "y": 200,
  "width": 50,
  "height": 30
}
```
```

--------------------------------

### Launch App with Arguments (JavaScript)

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods

Launches an application with specified bundle ID and custom arguments for language and locale. Ensure the app is terminated before launching with arguments if it's already running.

```javascript
await driver.executeScript('mobile:launchApp', [{
  bundleId: 'com.apple.Preferences',
  arguments: ['-AppleLanguages', '(ja)', '-AppleLocale', 'ja_JP']
}]);
```

--------------------------------

### List real devices using devicectl

Source: https://appium.github.io/appium-xcuitest-driver/latest/reference/scripts

List all connected real devices, using the `devicectl` service for discovery. This is primarily useful for tvOS devices.

```bash
appium driver run xcuitest list-real-devices -- --devicectl
```

--------------------------------

### Install Specific Appium XCUITest Driver Version

Source: https://appium.github.io/appium-xcuitest-driver/latest/getting-started/installation

Install a specific version of the XCUITest driver by appending the version number to the driver name.

```bash
appium driver install xcuitest@7.16.0

```