This is Appium driver for automating macOS applications using Apple's XCTest framework. The driver operates in scope of W3C WebDriver protocol with several custom extensions to cover operating-system specific scenarios. The original idea and parts of the source code are borrowed from the Facebook's WebDriverAgent project.

On top of standard Appium requirements Mac2 driver also expects the following prerequisites:

• macOS 11 or later
• Xcode 13 or later should be installed
  • xcode-select should be pointing to <full_path_to_xcode_app>/Contents/Developer developer directory instead of /Library/Developer/CommandLineTools to run xcodebuild commands
• Xcode Helper app should be enabled for Accessibility access. The app itself could be usually found at /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Agents/Xcode Helper.app. In order to enable Accessibility access for it simply open the parent folder in Finder: open /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Agents/ and drag & drop the Xcode Helper app to Security & Privacy -> Privacy -> Accessibility list of your System Preferences. This action must only be done once.
• testmanagerd process requires UIAutomation authentication since macOS 12. automationmodetool enable-automationmode-without-authentication command may help to disable it. This may be particularly useful in CI environments. Apple forum thread.

Since driver version 1.9.0 you can automate the validation for the most of the above requirements as well as various optional ones needed by driver extensions by running the appium driver doctor mac2 server command.

Mac2 driver supports the following element attributes:

These attribute values could be retrieved from the page source output and then used for elements location. See the official documentation on XCUIElementAttributes protocol for more details on each attribute.

Mac2 driver supports the following location strategies:

Check the integration tests for more examples on different location strategies usage.

Beside of standard W3C APIs the driver provides the below custom command extensions to execute platform specific scenarios. Use the following source code examples in order to invoke them from your client code:

// 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
));

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

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

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

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

Perform click gesture on an element or by relative/absolute coordinates

• click (XCUIElement)
• click (XCUICoordinate)

Perform scroll gesture on an element or by relative/absolute coordinates

• scrollByDeltaX:deltaY: (XCUIElement)
• scrollByDeltaX:deltaY: (XCUICoordinate)

Perform right click gesture on an element or by relative/absolute coordinates

• rightClick (XCUIElement)
• rightClick (XCUICoordinate)

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

• hover (XCUIElement)
• hover (XCUICoordinate)

Perform double click gesture on an element or by relative/absolute coordinates

• doubleClick (XCUIElement)
• doubleClick (XCUICoordinate)

Perform long click and drag gesture on an element or by absolute coordinates

• clickForDuration:thenDragToElement (XCUIElement)
• clickForDuration:thenDragToCoordinate: (XCUICoordinate)

Perform long click, drag and hold gesture on an element or by absolute coordinates

• clickForDuration:thenDragToElement:withVelocity:thenHoldForDuration: (XCUIElement)
• clickForDuration:thenDragToCoordinate:withVelocity:thenHoldForDuration: (XCUICoordinate)

This extension performs a swipe gesture on the particular screen element or by given coordinates. The API is only available on macOS since Xcode SDK 13.

• swipeDown (XCUIElement)
• swipeDown (XCUICoordinate)
• swipeDownWithVelocity: (XCUIElement)
• swipeDownWithVelocity: (XCUICoordinate)
• ...

Perform press gesture on a Touch Bar element or by relative/absolute coordinates

• pressForDuration: (XCUIElement)
• pressForDuration: (XCUICoordinate)

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

• tap (XCUIElement)
• tap (XCUICoordinate)

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

• doubleTap (XCUIElement)
• doubleTap (XCUICoordinate)

Perform long press and drag gesture on a Touch Bar element or by absolute Touch Bar coordinates

• pressForDuration:thenDragToElement: (XCUIElement)
• pressForDuration:thenDragToCoordinate: (XCUICoordinate)

Perform long press, drag and hold gesture on a Touch Bar element or by absolute Touch Bar coordinates

• pressForDuration:thenDragToElement:withVelocity:thenHoldForDuration: (XCUIElement)
• pressForDuration:thenDragToCoordinate:withVelocity:thenHoldForDuration: (XCUICoordinate)

Send keys to the given element or to the application under test

typedef NS_OPTIONS(NSUInteger, XCUIKeyModifierFlags) {
   XCUIKeyModifierNone       = 0,
   XCUIKeyModifierCapsLock   = (1UL << 0),
   XCUIKeyModifierShift      = (1UL << 1),
   XCUIKeyModifierControl    = (1UL << 2),
   XCUIKeyModifierOption     = (1UL << 3),
   XCUIKeyModifierCommand    = (1UL << 4),
   XCUIKeyModifierFunction   = (1UL << 5),
   // These values align with UIKeyModifierFlags and CGEventFlags.
   XCUIKeyModifierAlphaShift = XCUIKeyModifierCapsLock,
   XCUIKeyModifierAlternate  = XCUIKeyModifierOption,
};

• typeKey:modifierFlags:

Retrieves the string representation of the current application

The source of the current page in a string representation

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.

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.

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.

true if the app was running before being terminated

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

An integer value representing the application state. See the official documentation on XCUIApplicationState enumeration for more details.

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 Preferences -> Privacy list. See AppleScript Commands Execution for more details.

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

Record the display in background while the automated test is running. This method requires FFMPEG to be installed and present in PATH. Also, the Appium process must be allowed to access screen recording in System Preferences->Security & Privacy->Screen Recording. The resulting video uses H264 codec and is ready to be played by media players built-in into web browsers.

Stop recording the screen. If no screen recording has been started before then the method returns an empty string.

Base64-encoded content of the recorded media file if remotePath parameter is falsy or an empty string.

Retrieves a screenshot of each display available to macOS.

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

The Mac2 driver has the concept of Application Under Test. This is the app, whose bundle identifier has been passed as bundleId capability or as an argument to macos: activateApp or macos: launchApp extensions. If this application is unexpectedly terminated during test session execution then an exception is going to be thrown upon any following session command invocation. In such case the driver assumes the application under test is crashed and it is impossible to proceed. Also, the Application Under Test is going to be terminated when the testing session quits (unless canceled by skipAppKill capability). It is possible to reset the Application Under Test value to none by executing macos: terminateApp helper and providing the bundle identifier of this app to it. Also, macos: activateApp or macos: launchApp calls can change Application Under Test value if a bundle identifier different from the current one is provided to them.

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 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. Here's an example code of how to get a shell command output:

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

In theory it is possible to emulate a mouse gesture of any complexity with W3C actions. However, there is a set of "standard" gestures, where each operating system has its own requirements, like clicks, double clicks, etc. All such action parameters must comply with these requirements to be recognized properly. Here is a short list of examples for the most common macOS pointer gestures:

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

The duration of mouse button suppression should be 0-125 ms.

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

The duration of mouse button suppression should be 0-125 ms.

[
  {"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}
]

The duration between two clicks should be 600-1000 ms.

[
  {"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}
]

The longer is the duration of the second pointerMove action the lesser is the drag velocity and vice versa. One could add more pointerMove actions before releasing the mouse button to simulate complex cursor moving paths. Mac2Driver terminates action execution with a timeout error if the duration of it exceeds 5 minutes.

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

This snippet tells the mouse pointer to hover over [100, 100, 200, 200] area for 1 second. In general, hover action will be performed every time if there is no preceding pointerDown to the current pointerMove one or the preceding pointerDown action has been ended by the pointerUp one.

Mac2Driver supports Appium Settings API. Along with the common settings the following driver-specific settings are currently available:

# Python3 + PyTest
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'

Parallel execution of multiple Mac2 driver instances is highly discouraged. Only one UI test must be running at the same time, since the access to accessibility layer is single-threaded. Also HID devices, like the mouse or the keyboard, must be acquired exclusively.

The server part of the driver recognizes the following environment variables:

• ENABLE_AUTOMATIC_SCREENSHOTS: enables automatic XCTest screenshots. These screenshots are stored in the same folder where WDA test logs are located and are taken automatically. This feature is disabled by default. Only enable it if you know what you are doing otherwise these screenshots may quickly fill up the free disk space.
• ENABLE_AUTOMATIC_SCREEN_RECORDINGS: enables automatic XCTest screen recordings. These screen recordings are stored in the same folder where WDA test logs are located and are taken automatically. This feature is disabled by default. Only enable it if you know what you are doing otherwise these videos may quickly fill up the free disk space. The native screen recording feature only works on Xcode 15+.
• USE_PORT. If enabled then the server listens on the given port. Otherwise, a random free port from the 10100..10200 range is selected. By default, the port is selected by the driver (see the appium:systemPort capability description).
• VERBOSE_LOGGING. If enabled then server logs should include various verbose details. Disabled by default.

This module uses the same development tools as the other Appium drivers.

Check out the source. Then run:

npm install

Execute npm run test to run unit tests and npm run e2e-test to run integration tests.

• W3C actions support is limited (only mouse actions are supported). You could also use macos: extension APIs to cover your test scenarios