Set up Appium 2 to Automate macOS Apps

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

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:

/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Agents/

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

Set up Appium 2 to Run XCUITest (for iOS)

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.

appium

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': "com.apple.calculator",
  },
  appium_lib: {
    server_url: "http://127.0.0.1:4723",
    wait: 0.1,
  },
}
@driver = Appium::Driver.new(opts).start_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': "com.apple.calculator",
      },
      appium_lib: {
        server_url: "http://127.0.0.1:4723",
        wait: 0.1,
      },
    }
    @driver = Appium::Driver.new(opts).start_driver
  end

  def driver
    return @driver
  end

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

  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").last.click
    the_result = driver.find_element(:name, "main display").text
    expect(the_result).to eq("5")
  end

end

Run this Rspec test from the command line:

rspec add_calc_spec.rb

The output will be like below:

Troubleshooting

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.