How to Setup Appium on a Mac – Using Java and Appium Cheatsheet

As part of our How to Series, this article looks at how to set up Appium on Mac and also offer tips with an Appium cheatsheet for some quick Appium hacks. Read More posts from the How to Series on using Appium, Selenium, Soap UI and other tools.
It is almost certain that when we start using a new tool we will face some difficulty until we get it up and running. Therefore, it always good to maintain some kind of engineering log book or pocketbook, just like civil engineers had back in the day before the age of the digital computer.
Here is how you setup Appium on Mac:
  • Install brew package manager:
  • Make the hidden files appear:
  • Restart all finder windows so you can see hidden files:
  • Appium needs node.js so let us install this too!
  • Now let’s install Java
  • And finally let’s start installing appium
  • You must also install the android SDK tools from googles site as well as the latest Xcode version and the Xcode Command line tools
… read more to find out the final bullet points

When I started to search online on how to install and use Appium, all of the info was spread out in different articles, so I decided to make a type of handbook for setting up and using Appium quickly on a new machine (in this case mac), as well as for keeping in place various Appium methods that help me out with elements that are difficult to address. The following are not all necessary, but they do help in the long run, especially when you start to develop your Appium project (in this case I use a maven type project as a reference).


How to Setup Appium On A Mac For Android and iOS Devices

Star off by opening the mac os terminal and install the following to get it up and running:

Install brew package manager:

/usr/bin/ruby -e “$(curl -fsSL”
Note 1: if you face access write issues while trying to install brew run the following: sudo chown -R $USER:admin /usr/local
Note 2: will ask you to install xcode command line tools if you havn’t got any version of them installed

Make the hidden files appear:

defaults write AppleShowAllFiles YES

Restart all finder windows so you can see hidden files:

killall Finder

If you don’t have a bash_profile, make one, so you can set the environment variables for android and java later:

touch .bash_profile  (run this within your /Users/YourUsername/ path )

Appium needs node.js so let us install this too!

brew install node
npm install npm@latest -g
npm init  ( tap enter to all )

Now let’s install Java

brew install caskroom/cask/brew-cask
brew cask install java
If you are going to set up to run Appium using Java, then you need maven.
brew install maven

The following are needed for iOS devices.

brew install carthage
brew install libimobiledevice –HEAD
npm install -g ios-deploy ( make sure you have Xcode installed first ) 
brew install ideviceinstaller
And finally let’s start installing appium!
npm install -g appium
npm install wd
npm install appium-doctor -g

If you want a specific version of Appium use this:

npm install -g [email protected] ( e.g. npm install -g [email protected])

You must also install the android SDK tools from googles site as well as the latest Xcode version and the Xcode Command line tools

To install the android sdk tools go to the android developer website 

Or via the Terminal

brew tap caskroom/cask
brew cask install android-sdk

For Xcode go to the appstore and search for Xcode and install it.

Then run the following line in the terminal to install the command line tools:

xcode-select –install

Check if xcode is installed:

xcode-select -p

Check the version of the xcode command line tools:

pkgutil –

Also make sure you set the the following home environment variables. Open a terminal window and go to your user folder and type in:

open .bash_profile

The mac text editor will open up. There you should inlcude your android sdk and Java home paths. Depending on where you installed them these might be different. The file although should and up looking something like this:

export ANDROID_HOME=/Users/YourUsername/Library/Android/sdk
export PATH=${PATH}:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_121.jdk/Contents/Home
export M2_HOME=/usr/local/apache-maven/apache-maven-3.3.9
export M2=$M2_HOME/bin
export PATH=$M2:$PATH
export PATH=${JAVA_HOME}/bin:$PATH
export PATH=/usr/local/bin:$PATH

Now for a final check run this:


You should get all greens from the report something similar to the image below:

Appium setup for iOS devices

To starting using Appium and the Appium inspector for iOS devices you must first install the webdriveragent app to your iOS device.

Open a terminal and go to the folder below

cd /usr/local/lib/node_modules/appium/node_modules/appium-xcuitest-driver/WebDriverAgent

Now create the following directory:

mkdir -p /usr/local/lib/node_modules/appium/node_modules/appium-xcuitest-driver/WebDriverAgent/Resources/WebDriverAgent.bundle

Now run the following script

bash Scripts/ -d

Lastly build and install the webdriveragent app that will enable for Appium to talk to your device

xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination ‘id=af916cc5486cf9cb85ddde19f97949ecd6c62c66’ test

For more detailed steps follow the steps provided at the Appium github page




Appium Cheat Sheet

In this section I have gathered various “fixes” and “how to’s” for common troubleshooting situations but also some helpful Appium driver methods that are important for creating your testing scenarios.

Make Appium run faster on android by disabling animations.

Appium utilises the UIAutomator/UIAutomator2 Driver for android and the XCUITest driver for iOS. A common issue that you might face is that Appium is not that fast, when tapping and checking if elements exist, depending of the app complexity and android version. The native android espresso driver is super fast, if you have seen it, and currently the Appium devs are busy integrating it for the new version of Appium. Until then a simple way to overcome this is by disabling animations on your android phone. This makes tests run much faster but still not as the espresso driver. To disable the animations you need to activate the developer options on your android. To enable this mode do the following:

>Go to Settings -> About phone -> Build Number (tap on it as many times needed until you see the developer options activated) -> go back to settings, scroll down and you should see the dev options, tap on that and then scroll to the part where you disable the animations. Try running your tests again and you will notice the difference.

Appium cant start because port is occupied.

Sometimes, when you attempt to start the Appium inspector or run your Appium project, you might get an error that the port needed by Appium is occupied.

Kill the Appium server:

killall node

View your android and iOS connected devices:

This displays the devices serial number that is also uses for the UDID capability for appium, simply type in the terminal the following:

For android:

adb devices

For iOS devices:

system_profiler SPUSBDataType


How to find the accessibility ID’s, element names and xpaths of an application.

Appium provides a very handy application called appium desktop that you can find here:

The way appium desktop works is by firstly setting up your device capabilities within its UI interface and then starts an appium server in order to start your desired app and inspect it.

You can use this for android and iOS devices

android uiautomatorviewer

This is provided together with android sdk tools and can be found in the path below:


The advantage of this inspector is that you just plugin your android device and start the viewer without the need of starting an appium server.

Xcode Accessibility Inspector

Open up Xcode and make sure your iPhone is plugged in. On the menu bar choose Xcode -> Open developer Tool -> Accessibility Inspector and then choose your device.

Click on the target cursor in the window that opens and then perfom an actual tap on the iPhone. You will see the info of the tapped element appear in the Xcode window.

Usefull Appium Driver Methods

In this section I have gathered some useful Appium driver methods that will help you in doing specific actions or checks.

How to take a Device Screenshot with Appium

Take a screenshot of your phone so you can now what was displayed when your scenario crashes.

For android use this:

public AndroidDriver driver;
  public void getScreenshot(String outputlocation) throws IOException {
  File srcFiler=((TakesScreenshot)driver).getScreenshotAs(OutputType.FILE);
  FileUtils.copyFile(srcFiler, new File(outputlocation + “appImage” + “.png”));

For iOS:

File screenShot = appiumDriver.getScreenshotAs(OutputType.FILE);

Or by using the terminal command via Java:

Runtime.getRuntime().exec(“idevicescreenshot -u “+udid+” temp.tiff”);


How to swipe with Appium

There are a lot of methods out there on the internet and after my search the below methods are the ones that I have tested and can say they work. ( for me at least !) driver.navigate().to(“Log out”).

For android:

driver.swipe(start_x, start_y, end_x, end_y, duration)

But android has various sizes so if you want for instance to swipe from the center up you need to first get your coords of the centre of the current device.

  public void SwipeFromTheCenterUpwards(){
  Dimension size = driver.manage().window().getSize();
  int endy = (int) (size.height * 0.1);  // here we define how far it should swipe
  int endx = (int) (size.width * 0.5);   
  int startx = (int) (size.width * 0.50); // getting the half of the screens width
  int starty = (int) (size.height * 0.50);   // getting the half of the screens height
  driver.swipe(startx, starty, startx, endy, 1000); //  1000 is duration in milliseconds
  //driver.swipe wont work with Java-client 5 so you should use the following instead if you want to use the latest Java-client
  new TouchAction(this).press(startx, starty).waitAction(duration).moveTo(endx, endy).release().perform(); 

For iOS: (using Java client 5)

driver.performTouchAction(new IOSTouchAction(driver).press(elem).moveTo(0, elem.getLocation().getY()).release())

Otherwise you can also use the following for Java-client 4 version

driver.swipe(start_x, start_y, end_x, end_y, duration)


How to wait until elements are displayed

wait = new WebDriverWait(driver, duration);

How to click on using the accessibility ID


 Type something on your device



Of course there are many more useful commands that we use daily. These are just a few to give you an understanding of how things work in general. Hopefully, I will add some more in the near future. I hope you enjoyed this post. Feel free to comment below with your suggestions.
Take care and TEST!!



About the Author

Leonidas Kanellopoulos

Find out more about @leonidas-kanellopoulos