Set up Appium 2 to Automate macOS Apps

Setup and run an Appium 2 automated macOS test with Mac2Driver.

Courtney Zhan
4 min readDec 2, 2023


This tutorial will show you how to set up Appium v2 on a macOS computer to automate a simple macOS desktop app (Calculator).

Set up Appium Server

First, install NodeJS with HomeBrew:

brew upgrade node@18

Then, install Appium (v2) with NPM:

npm install -g appium

Configure macOS for Appium Server

Add XCodeHelper to Accessibility permissions.

Open System Preferences -> Privacy & Security -> Privacy -> Accessibility and add XcodeHelper.

You can find Xcode Helper in the below path, open it in Finder and drag it to System Preferences to add it:


For a more detailed installation guide, follow the setup steps in the below article:

Setup Appium Client

Install the Ruby Appium client library:

gem install --no-document appium_lib

Install the Appium Driver for macOS

Appium, like Selenium, drives an app via external driver software.

To show available drivers:

appium driver list

The output will look like this:

courtney@MacBook16 ~ % appium driver list
✔ Listing available drivers
- uiautomator2 [not installed]
- xcuitest [not installed]
- youiengine [not installed]
- windows [not installed]
- mac [not installed]
- mac2 [not installed]
- espresso [not installed]
- tizen [not installed]
- flutter [not installed]
- safari [not installed]
- gecko [not installed]

Install the macOS driver, Mac2Driver, mac2.

appium driver install mac2

Make sure you install mac2 instead of mac.
- Mac2Driver uses Apple’s XCTest and requires macOS 10.15 or later, and Xcode 12 or later to be installed.
- MacDriver requires installation of a separate application, AppiumForMac.

I recommend using Mac2Driver, so this guide is for mac2 only.

Start the Appium Server

Just run a simple command to start an Appium server.

Under “Available drivers” you should see mac2

Leave this open and running in a separate terminal window.

Automated Script

Below is a simple Appium automation script to open the Calculator app and print the app’s name.

require "appium_lib"
opts = {
caps: {
platformName: "mac",
'appium:automationName': "Mac2",
'appium:bundleId': "",
appium_lib: {
server_url: "",
wait: 0.1,
@driver =
application_element = @driver.find_element :class_name, 'XCUIElementTypeApplication'
application_name = application_element.attribute :title
puts application_name

Similar to the Appium options for mobile, appium:bundleId is used to identify a macOS app.

Save and run this script with ruby macos_sample.rb. If everything was installed and set up correctly, you should see the Calculator start up and Calculator printed on the console.

Test Created in TestWise IDE

If it is your first time, you might also be prompted for your login password to allow Appium to control your mouse/keyboard. Don’t worry, this is expected.

When the test begins, you will see an overlay on your screen that says “Automation Running. Press Control + Option + Command + . to stop”

Taking screenshot won’t capture the overlay text, this is an iPhone photo of my desktop in automation mode.

If Calculator opens but you do not see this overlay, please see the Troubleshooting section below.

Automated Test

The above is automation script, now let’s convert it to an automated test in Rspec, below:

load File.dirname(__FILE__) + "/../test_helper.rb"
describe "Calculator on macOS" do
include TestHelper # defined in ../test_helper.rb
before(:all) do
opts = {
caps: {
platformName: "mac",
'appium:automationName': "Mac2",
'appium:bundleId': "",
appium_lib: {
server_url: "",
wait: 0.1,
@driver =

def driver
return @driver

after(:all) do
@driver.quit unless debugging?

it "Single digit and subtract" do
driver.find_element(:name, "four").click
driver.find_element(:name, "add").click
driver.find_element(:name, "three").click
driver.find_element(:name, "subtract").click
driver.find_element(:name, "two").click
driver.find_elements(:name, "equals")
the_result = driver.find_element(:name, "main display").text
expect(the_result).to eq("5")


Run this Rspec test from the command line:

rspec add_calc_spec.rb

The output will be like below:


If you run into issues (e.g. Calculator starts up but test doesn’t run), restart the Appium Server.

As far as I can tell, closing the automation overlay (with Control + Option + Command + .) will prevent any new sessions from starting properly. This means, try not to close the overlay until you are sure you are finished. If you do close the overlay, make sure to stop the Appium server as well.

On a test machine, this is fine (we wouldn’t be manually closing the overlay during test execution anyway).

I think Appium2 + Mac2Driver is not mature yet for serious test automation, but may be helpful for some simple automation tasks.