### ExecuteScript Dotnet Example

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Demonstrates how to execute platform-specific scripts in Dotnet using `ExecuteScript`. Arguments are supplied in a dictionary.

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

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

### ExecuteScript Ruby Example

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Provides an example of using `execute_script` in Ruby to run custom macOS commands. Arguments are passed as a hash.

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

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

### Launching an Application with Arguments

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Start or activate an application with specified command line arguments. This argument is ignored if the app is already running.

```javascript
driver.launchApp({bundleId: 'com.example.app', arguments: ['--help']});
```

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

### ExecuteScript Python Example

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Illustrates invoking platform-specific commands via `execute_script` in Python. Arguments are provided as a dictionary.

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

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

### Install Dependencies for Mac2 Driver

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

This command installs the necessary Node.js dependencies for the Appium Mac2 driver development. Run this after cloning the repository.

```bash
npm install
```

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

### ExecuteScript Java Example

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Demonstrates how to invoke platform-specific commands using `executeScript` in Java 11+. The method name and arguments are passed as strings.

```java
// Java 11+
var result = driver.executeScript("macos: <methodName>", Map.of(
    "arg1", "value1",
    "arg2", "value2"
    // you may add more pairs if needed or skip providing the map completely
    // if all arguments are defined as optional
));
```

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

### Launching an Application by Path

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Start or activate an application using its full path. If the app is already running, it will be activated. This command influences the Application Under Test.

```javascript
driver.launchApp({path: '/Applications/Xcode.app'});
```

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

### Retrieving Application Source (XML)

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Get the source of the current application formatted as XML. This is the default format.

```javascript
driver.source('xml');
```

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

### ExecuteScript WebdriverIO Example

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Shows how to use `executeScript` in WebdriverIO to call platform-specific methods. Arguments are passed as an array of objects.

```javascript
// WebdriverIO
const result = await driver.executeScript('macos: <methodName>', [{
    arg1: "value1",
    arg2: "value2",
}]);
```

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

### Launching an Application by Bundle ID

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Start or activate an application using its bundle identifier. If the app is already running, it will be activated. This command influences the Application Under Test.

```javascript
driver.launchApp({bundleId: 'com.apple.TextEdit'});
```

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

### macos: startRecordingScreen

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Starts recording the screen with various configurable options. This method allows for customization of video filters, frame rate, cursor capture, click capture, time limits, and restart behavior.

```APIDOC
## macos: startRecordingScreen

### Description
Starts recording the screen with various configurable options. This method allows for customization of video filters, frame rate, cursor capture, click capture, time limits, and restart behavior.

### Arguments
#### Path Parameters
- **deviceId** (number) - yes - Screen device index to use for the recording. The list of available devices could be retrieved using `ffmpeg -f avfoundation -list_devices true -i` command.
- **videoFilter** (string) - no - The video filter spec to apply for ffmpeg. See https://trac.ffmpeg.org/wiki/FilteringGuide for more details on the possible values. Set it to `scale=ifnot(gte(iw\,1024)\,iw\,1024):-2` in order to limit the video width to 1024px. The height will be adjusted automatically to match the actual ratio.
- **fps** (number) - no - The count of frames per second in the resulting video. The greater fps it has the bigger file size is. The default vale is `15`.
- **preset** (string) - no - One of the supported encoding presets. Possible values are: `ultrafast`, `superfast`, `veryfast` (the default value), `faster`, `fast`, `medium`, `slow`, `slower`, `veryslow`. A preset is a collection of options that will provide a certain encoding speed to compression ratio. A slower preset will provide better compression (compression is quality per filesize). This means that, for example, if you target a certain file size or constant bit rate, you will achieve better quality with a slower preset. Read https://trac.ffmpeg.org/wiki/Encode/H.264 for more details.
- **captureCursor** (boolean) - no - Whether to capture the mouse cursor while recording the screen. `false` by default.
- **captureClicks** (boolean) - no - Whether to capture mouse clicks while recording the screen. `false` by default.
- **timeLimit** (number) - no - The maximum recording time, in seconds. The default value is 600 seconds (10 minutes).
- **forceRestart** (boolean) - no - Whether to ignore the call if a screen recording is currently running (`false`) or to start a new recording immediately and terminate the existing one if running (`true`, the default value).
```

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

### macos: launchApp

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Starts an app with the given bundle identifier or activates it if the app is already running. An exception is thrown if the app with the given identifier cannot be found.

```APIDOC
## macos: launchApp

### Description
Start an app with the given bundle identifier or activates it if the app is already running. An exception is thrown if the app with the given identifier cannot be found.
This API influences the state of the [Application Under Test](#application-under-test-concept).

### Arguments
#### Path Parameters
- **bundleId** (string) - Optional - Bundle identifier of the app to be launched or activated. Either this argument or the `path` one must be provided.
- **path** (string) - Optional - Full path to the app bundle. Either this argument or the `bundleId` one must be provided.
- **arguments** (array) - Optional - The list of command line arguments for the app to be be launched with. This argument is ignored if the app is already running.
- **environment** (dictionary) - Optional - Environment variables mapping. Custom variables are added to the default process environment. This argument is ignored if the app is already running.

### Returns
None
```

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

### Launching an Application with Environment Variables

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Start or activate an application with custom environment variables. These variables are added to the default process environment and are ignored if the app is already running.

```javascript
driver.launchApp({bundleId: 'com.example.app', environment: { myEnvVar: 'value' }});
```

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

### Element Location Strategies Table

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Details the supported element location strategies for the Mac2 driver, including their descriptions, speed ranking, and pseudocode examples.

```markdown
Name | Description | Speed Ranking | Pseudocode
--- | --- |  --- | ---
accessibilityId, id, name | These all strategies are mapped to the same Mac2 driver ByIdentifier lookup strategy. The locator matches the passed value with element's `identifier` attribute case-sensitively. | `⭐⭐⭐⭐⭐` | AppiumBy.accessibilityId("identifier"), By.id("identifier"), By.name("identifier")
className | Class name uses stringified element types for lookup | `⭐⭐⭐⭐⭐` | By.className("XCUIElementTypePopUpButton")
predicate | Lookup by predicate is natively supported by XCTest and is as fast as previous lookup strategies. This lookup strategy could only use the supported [element attributes](#element-attributes). Unknown attribute names would throw an exception. Check [NSPredicate cheat sheet](https://academy.realm.io/posts/nspredicate-cheatsheet/) for more details on how to build effective and flexible locators. | `⭐⭐⭐⭐⭐` | AppiumBy.iOSNsPredicateString("elementType == 2 AND label BEGINSWITH 'Safari'")
classChain | This strategy is a combination of Xpath flexibility and fast predicate lookup. Prefer it over Xpath unless there is no other way to build the desired locator. Visit [Class Chain Construction Rules tutorial](https://github.com/facebookarchive/WebDriverAgent-wiki/wiki/Class-Chain-Queries-Construction-Rules) to get more knowledge on how to build class chain locators. | `⭐⭐⭐⭐` | AppiumBy.iOSClassChain("**/XCUIElementTypeRuler[$elementType == 72 AND value BEGINSWITH '10'$")
xpath | For elements lookup XPath strategy the driver uses the same XML tree that is generated by page source API. [XPath 2.0](https://www.w3.org/TR/xpath20/) is supported since driver version 1.20.0. All driver versions below 1.20.0 only support XPath 1.0 (based on xmllib2). | `⭐⭐⭐` | By.xpath("//XCUIElementTypePopUpButton[@value=\"Regular\" and @label=\"type face\"]")
```

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

### Retrieving Application Source (Description)

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Get the source of the current application formatted as a debug description string. Refer to the XCUIElement's debugDescription method for more details.

```javascript
driver.source('description');
```

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

### Get Display Information

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Fetches information about available displays on the macOS system. Returns a map of display identifiers to display info objects.

```javascript
const displays = await driver.executeScript("macos: listDisplays", {});
console.log(displays);
```

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

### macos: stopNativeScreenRecording

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Stops the native screen recording started by `macos: startNativeScreenRecording` and returns the video payload or uploads it to a remote location. The video file is removed locally after successful consumption. Throws an exception if no recording was started previously. Requires Xcode version 15+.

```APIDOC
## macos: stopNativeScreenRecording

### Description
Stops native screen recording previously started by
[macos: startNativeScreenRecording](#macos-startnativescreenrecording)
and returns the video payload or uploads it to a remote location,
depending on the provided arguments. The actual video file is removed from the local file system after the video payload is
successfully consumed. If no screen recording has been started before then this API throws an exception. Xcode must be at version 15+.

> [!IMPORTANT]
> In order to retrieve the recorded video from the local file system the Appium Server process itself
> or its parent process (e.g. Terminal) must have the "Full Disk Access" permission granted
> in 'System Settings'→'Privacy & Security' tab.

> [!NOTE]
> Be careful while recording lengthy videos. They could be pretty large, and may easily exceed
> the free space on the home partition.

### Arguments
#### Query Parameters
- **remotePath** (string) - Optional - The path to the remote location, where the resulting video should be uploaded. The following protocols are supported: http/https, ftp. Null or empty string value (the default setting) means the content of resulting file should be encoded as Base64 and passed as the endpoint response value. An exception will be thrown if the generated media file is too big to fit into the available process memory. Example: https://myserver.com/upload/video.mp4
- **user** (string) - Optional - The name of the user for the remote authentication. Example: myname
- **pass** (string) - Optional - The password for the remote authentication. Example: mypassword
- **method** (string) - Optional - The http multipart upload method name. The 'PUT' one is used by default. Example: POST
- **headers** (map) - Optional - Additional headers mapping for multipart http(s) uploads. Example: `{"header": "value"}`
- **fileFieldName** (string) - Optional - The name of the form field, where the file content BLOB should be stored for http(s) uploads. `file` by default. Example: payload
- **formFields** (Map or `Array<Pair>`) - Optional - Additional form fields for multipart http(s) uploads. Example: `{"field1": "value1", "field2": "value2"}` or `[["field1", "value1"], ["field2", "value2"]]`
- **ignorePayload** (boolean) - Optional - Whether to ignore the resulting video payload and return an empty string. Useful if you prefer to fetch video chunks via the [appium:mac2.nativeVideoRecordingChunkAdded](./docs/bidi.md#appiummac2nativevideorecordingchunkadded) BiDi event. false by default. Example: true

### Returns
#### Success Response
- **string** - The video payload as a Base64 encoded string, or an empty string if `ignorePayload` is true or if the video was uploaded remotely.
```

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

### Element Attributes Table

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Lists supported element attributes for the Mac2 driver, including their descriptions and example values. These attributes can be used for element location.

```markdown
Name | Description | Example
--- | --- | ---
elementType | Integer-encoded element class. See the official documentation on [XCUIElementType enumeration](https://developer.apple.com/documentation/xctest/xcuielementtype?language=objc) for more details. | '2'
frame | Coordinates of bounding element rectangle | {x: 1, y: 2.5, width: 100, height: 200}
placeholderValue | It is usually only present for text fields. For other element types it's mostly empty | 'my placeholder'
enabled | Contains `true` if the element is enabled | 'false'
focused | Contains `true` if the element has the keyboard input focus | 'false'
selected | Contains `true` if the element is selected | 'false'
hittable | Contains `true` if the element is hittable | 'true'
label | Element's label value. Could be empty | 'my label'
title | Element's title value. Could be empty | 'my title'
identifier | Element's accessibility identifier. Could be empty | 'identifier'
value | The value could be different depending on the actual element type. For example, text fields might have their text context there and sliders would contain the float position value, while switches would have either `1` or `0` | '1.5'
```

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

### Get macOS Clipboard Content

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Retrieves the macOS clipboard content as a base64-encoded string. Supports plaintext, image, and URL content types. Returns an empty string if no data is found for the specified type.

```javascript
const clipboardContent = await driver.executeScript("macos: getClipboard", {
  contentType: "plaintext"
});
console.log(clipboardContent);
```

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

### macos: startRecordingScreen

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Records the display in the background while the automated test is running. Requires FFMPEG and screen recording permissions.

```APIDOC
## macos: startRecordingScreen

### Description
Record the display in background while the automated test is running. This method requires [FFMPEG](https://www.ffmpeg.org/download.html) to be installed and present in PATH. Also, the Appium process must be allowed to access screen recording in System Settings->Security & Privacy->Screen Recording. The resulting video uses H264 codec and is ready to be played by media players built-in into web browsers.

### Method
POST

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

### Parameters
(No parameters are explicitly documented for this method in the source text.)

### Returns
(The return value is not explicitly documented in the source text.)
```

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

### Activating an Application by Path

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Activate an application using its full path. An exception is thrown if the app is not found or not running. This command influences the Application Under Test.

```javascript
driver.activateApp({path: '/Applications/Xcode.app'});
```

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

### macos: source

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Retrieves the string representation of the current application's source code in either XML or description format.

```APIDOC
## macos: source

### Description
Retrieves the string representation of the current application.

### Arguments
#### Path Parameters
- **format** (string) - Required - The format of the application source to retrieve. Only two formats are supported: `xml` (returns the source formatted as XML document, the default value) and `description` (returns the source formatted as debugDescription output).

### Returns
The source of the current page in a string representation
```

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

### macos: queryAppState

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Queries the state of an application using its bundle identifier or path. An exception is thrown if the app cannot be found.

```APIDOC
## macos: queryAppState

### Description
Query an app state with given bundle identifier. An exception is thrown if the app cannot be found.

### Method
POST

### Endpoint
/session/:sessionId/appium/mac/query_app_state

### Parameters
#### Query Parameters
- **bundleId** (string) - Optional - Bundle identifier of the app to be queried. Either this argument or the `path` one must be provided. Example: com.apple.TextEdit
- **path** (string) - Optional - Full path to the app bundle. Either this argument or the `bundleId` one must be provided. Example: /Applications/Xcode.app

### Returns
An integer value representing the application state. See the official documentation on [XCUIApplicationState enumeration](https://developer.apple.com/documentation/xctest/xcuiapplicationstate?language=objc) for more details.
```

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

### macos: startNativeScreenRecording

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Initiates a new native screen recording session via XCTest. If a screen recording is already running, this call is a no-op. Recordings are active until the testing session ends and are automatically stopped and deleted if not explicitly stopped.

```APIDOC
## macos: startNativeScreenRecording

### Description
Initiates a new native screen recording session via XCTest. If the screen recording is already running then this call results in noop. A screen recording is running until a testing session is finished. If a recording has never been stopped explicitly during a test session then it would be stopped automatically upon the test session termination, and leftover videos would be deleted as well. Xcode must be at version 15+.

> [!TIP]
> Invocation of this API also triggers broadcasting of
> [appium:mac2.nativeVideoRecordingChunkAdded](./docs/bidi.md#appiummac2nativevideorecordingchunkadded)
> BiDi events. Make sure to subscribe to such events **before** this API is invoked to ensure
> all video chunks are being properly consumed on the client side.

### Arguments
#### Query Parameters
- **fps** (number) - Optional - Frame Per Second setting for the resulting screen recording. 24 by default. Higher FPS values may significantly increase the size of the resulting video. Example: 60
- **codec** (number) - Optional - Possible codec value, where `0` means H264 (the default setting), `1` means HEVC. Example: 1
- **displayId** (number) - Optional - Valid display identifier to record the video from. Main display ID is assumed by default. Use the `system_profiler -json SPDisplaysDataType` Terminal command to list IDs of connected displays or the [macos: listDisplays](#macos-listdisplays) API. Example: 1

### Returns
#### Success Response
The information about the asynchronously running video recording, which includes the following items:
- **fps** (number) - Frame Per Second value. Example: 24
- **codec** (number) - Codec value, where `0` means H264 (the default setting), `1` means HEVC. Example: 1
- **displayId** (number) - Display identifier used to record this video for. Example: 1
- **uuid** (string) - Unique video identifier. It is also used by XCTest to store the video on the file system. Look for `$HOME/Library/Daemon Containers/<testmanager_id>/Data/Attachments/<uuid>` to find the appropriate video file. Add the `.mp4` extension to it to make it openable by video players.
- **startedAt** (number) - Unix timestamp of the video startup moment. Example: 123456789
```

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

### Activating an Application by Bundle ID

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Activate an application using its bundle identifier. An exception is thrown if the app is not found or not running. This command influences the Application Under Test.

```javascript
driver.activateApp({bundleId: 'com.apple.Finder'});
```

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

### Run Tests for Mac2 Driver

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

These commands execute the unit and integration tests for the Appium Mac2 driver. Use 'npm run test' for unit tests and 'npm run e2e-test' for integration tests.

```bash
npm run test
```

```bash
npm run e2e-test
```

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

### macos: activateApp

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Activates an app with the given bundle identifier. An exception is thrown if the app with the given identifier cannot be found or if the app is not running.

```APIDOC
## macos: activateApp

### Description
Activates an app with the given bundle identifier. An exception is thrown if the app with the given identifier cannot be found or if the app is not running.
This API influences the state of the [Application Under Test](#application-under-test-concept).

### Arguments
#### Path Parameters
- **bundleId** (string) - Optional - Bundle identifier of the app to be activated. Either this argument or the `path` one must be provided.
- **path** (string) - Optional - Full path to the app bundle. Either this argument or the `bundleId` one must be provided.

### Returns
None
```

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

### macos: listDisplays

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Fetches information about available displays on the macOS system. Returns a map of display identifiers to their details.

```APIDOC
## macos: listDisplays

### Description
Fetches information about available displays.

### Returns
A map where keys are display identifiers represented as strings and values are display infos containing the following items:

Name | Type | Description | Example
--- | --- | --- | ---
id | number | Display identifier | 12345
isMain | boolean | Is `true` if the display is configured as a main system display | false
```

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

### macos: setClipboard

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Sets the macOS clipboard content. The content is provided as a base64-encoded string. Existing content will be cleared.

```APIDOC
## macos: setClipboard

### Description
Set the macOS clipboard content as base64-encoded string. The existing clipboard content (if present) will be cleared.

### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
content | string | yes | The content to be set as base64 encoded string | hello
contentType | string | no | The type of the content to set. Only `plaintext` (default), `image` and `url` are supported. If set to `url`, then `content` must be a valid URL. If set to `image`, then `content` must contain a valid PNG or TIFF image payload. | url
```

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

### W3C Click Action

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Emulates a standard mouse click at the specified coordinates. The duration of mouse button suppression should be between 0-125 ms.

```json
[
  {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
  {"type": "pointerDown", "button": 0},
  {"type": "pause", "duration": 100},
  {"type": "pointerUp", "button": 0}
]
```

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

### macos: getClipboard

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Retrieves the macOS clipboard content as a base64-encoded string. Supports specifying the content type.

```APIDOC
## macos: getClipboard

### Description
Get the macOS clipboard content as base64-encoded string.

### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
contentType | string | no | The type of the content to get. Only `plaintext` (default), `image` and `url` are supported. | image

### Returns
The actual clipboard content encoded into base64 string. An empty string is returned if the clipboard
contains no data for the given content type.
```

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

### macos: getNativeScreenRecordingInfo

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Fetches the information of the currently running native video recording. Requires Xcode version 15+.

```APIDOC
## macos: getNativeScreenRecordingInfo

### Description
Fetches the information of the currently running native video recording. Xcode must be at version 15+.

### Returns
#### Success Response
Either `null` if no native video recording is currently active or the same map that [macos: startNativeScreenRecording](#macos-startnativescreenrecording) returns.
```

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

### W3C Double Click Action

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Emulates a double mouse click at the specified coordinates. The duration between the two clicks should be between 600-1000 ms.

```json
[
  {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
  {"type": "pointerDown", "button": 0},
  {"type": "pointerUp", "button": 0},
  {"type": "pause", "duration": 1000},
  {"type": "pointerDown", "button": 0},
  {"type": "pointerUp", "button": 0}
]
```

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

### Python Appium Test for TextEdit

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

This snippet demonstrates how to use the Appium Mac2 driver with Python and PyTest to interact with the TextEdit application. It covers finding elements, sending keys, and clearing text fields. Ensure Appium client version 2.6.0 or later for options.

```python
import pytest

from appium import webdriver
# Options are available in Python client since v2.6.0
from appium.options.mac import Mac2Options
from appium.webdriver.common.appiumby import AppiumBy


@pytest.fixture()
def driver():
    options = Mac2Options()
    options.bundle_id = 'com.apple.TextEdit'
    # The default URL is http://127.0.0.1:4723/wd/hub in Appium1
    drv = webdriver.Remote('http://127.0.0.1:4723', options=options)
    yield drv
    drv.quit()


def test_edit_text(driver):
    edit_field = driver.find_element(by=AppiumBy.CLASS_NAME, value='XCUIElementTypeTextView')
    edit_field.send_keys('hello world')
    assert edit_field.text == 'hello world'
    edit_field.clear()
    assert edit_field.text == ''


def test_sending_custom_keys(driver):
    edit_field = driver.find_element(by=AppiumBy.CLASS_NAME, value='XCUIElementTypeTextView')
    flagsShift = 1 << 1
    driver.execute_script('macos: keys', {
        'keys': [{
            'key': 'h',
            'modifierFlags': flagsShift,
        }, {
            'key': 'i',
            'modifierFlags': flagsShift,
        }]
    })
    assert edit_field.text == 'HI'
```

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

### macos: screenshots

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Retrieves screenshots of all available displays on macOS. Optionally, a specific display can be targeted using its ID.

```APIDOC
## macos: screenshots

### Description
Retrieves a screenshot of each display available to macOS.

### Arguments
#### Path Parameters
- **displayId** (number) - no - Display identifier to take a screenshot for. If not provided then all display screenshots are going to be returned. If no matches were found then an error is thrown. Use the `system_profiler -json SPDisplaysDataType` Terminal command to list IDs of connected displays or the [macos: listDisplays](#macos-listdisplays) API.

#### Returns
A list of dictionaries where each item has the following keys:
- `id`: Display identifier
- `isMain`: Whether this display is the main one
- `payload`: The actual PNG screenshot data encoded to base64 string
```

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

### W3C Right Click Action

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Emulates a right mouse click at the specified coordinates. The duration of mouse button suppression should be between 0-125 ms.

```json
[
  {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
  {"type": "pointerDown", "button": 2},
  {"type": "pointerUp", "button": 2}
]
```

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

### W3C Hover Action

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Simulates a hover action by moving the mouse pointer over a specified area for a duration. Hover actions occur if there's no preceding pointerDown or if it has been ended by pointerUp.

```json
[
  {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
  {"type": "pointerMove", "duration": 1000, "x": 200, "y": 200}
]
```

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

### CDDL Schema for Native Video Recording Chunk Added Event

Source: https://github.com/appium/appium-mac2-driver/blob/master/docs/bidi.md

This CDDL schema defines the structure for the `appium:mac2.nativeVideoRecordingChunkAdded` event. It specifies the required 'method' and 'params' fields, including 'uuid' and 'payload'.

```cddl
appium:mac2.nativeVideoRecordingChunkAdded = {
  method: "appium:mac2.nativeVideoRecordingChunkAdded",
  params: {
    uuid: text,
    payload: text,
  },
}
```

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

### macos: click

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Performs a click gesture on a specified element or at given coordinates. Supports optional key modifiers.

```APIDOC
## macos: click

### Description
Performs a click gesture on an element or by relative/absolute coordinates.

### Method
POST

### Endpoint
`/session/:sessionId/click

### Parameters
#### Query Parameters
- **elementId** (string) - Optional - Unique identifier of the element to perform the click on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute coordinates.
- **x** (number) - Optional - Click X coordinate. Required if `y` is set or `elementId` is unset.
- **y** (number) - Optional - Click Y coordinate. Required if `x` is set or `elementId` is unset.
- **keyModifierFlags** (number) - Optional - If set, the given key modifiers will be applied while click is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details.

### Request Example
```json
{
  "elementId": "21045BC8-013C-43BD-9B1E-4C6DC7AB0744",
  "x": 100,
  "y": 100,
  "keyModifierFlags": 3
}
```

### Response
#### Success Response (200)
This endpoint typically returns an empty response body on success.

#### Response Example
```json
{}
```
```

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

### macos: appleScript

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Executes a given AppleScript command or script. This method supports specifying a command, a script, language overrides, timeouts, and working directories.

```APIDOC
## macos: appleScript

### Description
Executes the given AppleScript command or a whole script based on the given options. Either of these options must be provided. If both are provided then the `command` one gets the priority. Note that AppleScript command cannot contain line breaks. Consider making it to a script in such case. Note that by default AppleScript engine blocks commands/scripts execution if your script is trying to access some private entities, like cameras or the desktop screen and no permissions to do it are given to the parent (for example, Appium or Terminal) process in System Settings -> Privacy list. See [AppleScript Commands Execution](#applescript-commands-execution) for more details.

### Method
POST

### Endpoint
/session/:sessionId/appium/mac/applescript

### Parameters
#### Query Parameters
- **command** (string) - Yes if `script` is not provided - AppleScript command to execute. Example: `do shell script "echo hello"`
- **script** (string) - Yes if `command` is not provided - AppleScript script to execute. Example: `do shell script "echo hello"\ndo shell script "echo hello2"`
- **language** (string) - Optional - Overrides the scripting language. Basically, sets the value of `-l` command line argument of `osascript` tool. If unset the AppleScript language is assumed. Example: JavaScript
- **timeout** (number) - Optional - The number of seconds to wait until a long-running blocking command is finished. An error is thrown if the command is still running after this timeout expires. Example: 60000
- **cwd** (string) - Optional - The path to an existing folder which is going to be set as the working directory for the command/script being executed. Example: `/tmp`

### Returns
The actual stdout of the provided script if its execution was successful (e.g. got zero return code).
```

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

### macos: deepLink

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Opens a specified URL using either the default application associated with the URL scheme or a specific application identified by its bundle ID.

```APIDOC
## macos: deepLink

### Description
Opens the given URL with the default or the given application. Xcode must be at version 14.3+.

### Arguments
#### Path Parameters
- **url** (string) - yes - The URL to be opened. This parameter is manadatory.
- **bundleId** (string) - no - The bundle identifier of an application to open the given url with. If not provided then the default application for the given url scheme is going to be used.
```

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

### macos: performAccessibilityAudit

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Performs an accessibility audit for the current application under test. Requires Xcode 15 or later.

```APIDOC
## macos: performAccessibilityAudit

### Description
Performs an accessibility audit for the current application under test.
Xcode must be at version 15+.

### Arguments

Name | Type | Required | Description | Example
--- | --- | --- | --- | ---
auditTypes | array<string> | no | A list of audit type names as defined by [XCUIAccessibilityAuditType](https://developer.apple.com/documentation/xcuiautomation/xcuiaccessibilityaudittype?language=objc). If not provided then `XCUIAccessibilityAuditTypeAll` is used. | `['XCUIAccessibilityAuditTypeContrast']`

### Returns
An array of audit issue objects. Each item includes:
- `detailedDescription`: human-readable issue details
- `compactDescription`: short issue summary
- `auditType`: the resolved audit type name
- `element`: string representation of the affected element
- `elementDescription`: debug description of the affected element
```

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

### Execute Shell Command via AppleScript

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Executes a shell command using AppleScript. The 'macos: appleScript' command requires the 'apple_script' insecure feature to be enabled on the server. The output of the shell command is returned.

```java
// java
String appleScript = "do shell script \"echo hello\"";
System.out.println(driver.executeScript("macos: appleScript", ImmutableMap.of("command", appleScript)));
```

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

### W3C Drag and Drop Action

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Emulates a drag and drop gesture. The duration of the second pointerMove action affects drag velocity. Mac2Driver has a 5-minute timeout for action execution.

```json
[
  {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
  {"type": "pointerDown", "button": 0},
  {"type": "pause", "duration": 600},
  {"type": "pointerMove", "duration": 10, "x": 200, "y": 200},
  {"type": "pointerUp", "button": 0}
]
```

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

### macos: appleScript

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Executes custom AppleScript commands or scripts. Requires explicit enabling of the 'apple_script' insecure feature.

```APIDOC
## macos: appleScript

### Description
There is a possibility to run custom AppleScript from your client code. This feature is potentially insecure and thus needs to be explicitly enabled when executing the server by providing `apple_script` key to the list of enabled insecure features. Check [Appium Security document](https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/security.md) for more details. It is possible to either execute a single AppleScript command (use the `command` argument) or a whole script (use the `script` argument) and get its stdout in response. If the script execution returns non-zero exit code then an exception is going to be thrown. The exception message will contain the actual stderr. If the script is a blocking one then it could only run up to 20 seconds long. After that the script will be terminated and a timeout error will be thrown. This timeout could be customized by providing the `timeout` option value. You could also customize the script working directory by providing the `cwd` option.

### Example
```java
// java
String appleScript = "do shell script \"echo hello\"";
System.println(driver.executeScript("macos: appleScript", ImmutableMap.of("command", appleScript)));
```
```

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

### macos: hover

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Performs a hover gesture on a specified element or at given coordinates. Supports optional key modifiers.

```APIDOC
## macos: hover

### Description
Perform hover gesture on an element or by relative/absolute coordinates.

### Method
POST

### Endpoint
`/session/:sessionId/hover

### Parameters
#### Query Parameters
- **elementId** (string) - Optional - Unique identifier of the element to perform the hover on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute coordinates.
- **x** (number) - Optional - Long click X coordinate. Required if `y` is set or `elementId` is unset.
- **y** (number) - Optional - Long click Y coordinate. Required if `x` is set or `elementId` is unset.
- **keyModifierFlags** (number) - Optional - If set, the given key modifiers will be applied while hover is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details.

### Request Example
```json
{
  "elementId": "21045BC8-013C-43BD-9B1E-4C6DC7AB0744",
  "x": 100,
  "y": 100,
  "keyModifierFlags": 3
}
```

### Response
#### Success Response (200)
This endpoint typically returns an empty response body on success.

#### Response Example
```json
{}
```
```

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

### mobile: dragFromToForDuration

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Performs a drag gesture from a source element to a destination element or coordinates for a specified duration.

```APIDOC
## mobile: dragFromToForDuration

### Description
Performs a drag gesture from a source element to a destination element or coordinates for a specified duration.

### Method
POST

### Endpoint
/session/:sessionId/wda/dragfromtofor

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The session ID of the WebDriver session.

#### Request Body
- **sourceElementId** (string) - Optional - Uuid of the element to start the drag from. Required if `startX`, `startY`, `endX`, and `endY` are unset or if `destinationElementId` is set.
- **destinationElementId** (string) - Optional - Uuid of the element to end the drag on. Required if `startX`, `startY`, `endX`, and `endY` are unset or if `sourceElementId` is set.
- **startX** (number) - Optional - Starting X coordinate. Required if `sourceElementId` and `destinationElementId` are unset.
- **startY** (number) - Optional - Starting Y coordinate. Required if `sourceElementId` and `destinationElementId` are unset.
- **endX** (number) - Optional - End X coordinate. Required if `sourceElementId` and `destinationElementId` are unset.
- **endY** (number) - Optional - End Y coordinate. Required if `sourceElementId` and `destinationElementId` are unset.
- **duration** (number) - Required - The number of float seconds to hold the mouse button.
- **holdDuration** (number) - Required - Touch hold duration in float seconds.
- **velocity** (number) - Optional - Dragging velocity in pixels per second. If not provided then the default velocity is used.
- **keyModifierFlags** (number) - Optional - If set then the given key modifiers will be applied while drag is performed.
```

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

### macos: terminateApp

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Terminates an application identified by its bundle identifier or path. This action affects the state of the Application Under Test.

```APIDOC
## macos: terminateApp

### Description
Terminate an app with the given bundle identifier. An exception is thrown if the app cannot be found. This API influences the state of the [Application Under Test](#application-under-test-concept).

### Method
POST

### Endpoint
/session/:sessionId/appium/mac/terminate_app

### Parameters
#### Query Parameters
- **bundleId** (string) - Optional - Bundle identifier of the app to be terminated. Either this argument or the `path` one must be provided. Example: com.apple.Finder
- **path** (string) - Optional - Full path to the app bundle. Either this argument or the `bundleId` one must be provided. Example: /Applications/Xcode.app

### Returns
`true` if the app was running before being terminated
```

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

### macos: tap

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Performs a tap gesture on a Touch Bar element or by relative/absolute coordinates.

```APIDOC
## macos: tap

### Description
Perform tap gesture on a Touch Bar element or by relative/absolute coordinates

### Method
POST

### Endpoint
`/session/:sessionId/touch/click`

### Parameters
#### Arguments
- **elementId** (string) - Optional - Unique identifier of a Touch Bar element to perform the tap on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute Touch Bar coordinates.
- **x** (number) - Optional - click X coordinate
- **y** (number) - Optional - click Y coordinate
- **keyModifierFlags** (number) - Optional - if set then the given key modifiers will be applied while the gesture is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details
```

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

### macos: pressForDuration

Source: https://github.com/appium/appium-mac2-driver/blob/master/README.md

Performs a long press gesture on a Touch Bar element or by relative/absolute coordinates. The press duration can be specified.

```APIDOC
## macos: pressForDuration

### Description
Performs a long press gesture on a Touch Bar element or by relative/absolute coordinates. The press duration can be specified.

### Method
POST

### Endpoint
`/session/:sessionId/touch/longpress`

### Parameters
#### Arguments
- **elementId** (string) - Optional - Unique identifier of a Touch Bar element to perform the press on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute Touch Bar coordinates.
- **x** (number) - Optional - long click X coordinate
- **y** (number) - Optional - long click Y coordinate
- **duration** (number) - Required - The number of float seconds to hold the touch
- **keyModifierFlags** (number) - Optional - if set then the given key modifiers will be applied while the gesture is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details
```