A Guide to Setting up Appium (with WebdriverIO) and Run Tests for IOS and Android

With the advancements in the IT industry, the mobile app development is getting more and more widespread. But to be sure that the apps do not end up being released in a broken state, testing is required.

While manual testing approach can certainly do the job, more and more projects are interested in automating their testing process. One of the most popular tools for mobile automation is Appium. But setting Appium up can be a confusing process. Today, we will take a look at how things should be done in order for your automation tests to start.

This guide will encompass both iOS and Android-specific things, so you will not have to worry about only one platform working. But before we get to that, let’s discuss the advantages of Appium, as this is our Automation tool of choice.

Why Appium?

First of all, it is free and open-source, and has a huge base of users, so if you run into any issues, you can be sure that you can find help online.

Another advantage of Appium is that it can give you the capability to work with native, hybrid and web-apps, not to mention that Appium supports a variety of programming languages, such as JavaScript, Python, Ruby, C# and Java, so most of the programmers can start automating without a need to switch their language of choice.

Also, it supports cross-platform testing, meaning that if you want to make sure that your mobile application flows are the same regardless of the platform, this tool is right for you (it should be mentioned, however, that device-specific things like permissions are still handled a little differently).

However, while having those significant advantages, it also has some disadvantages, such as a complex setup. But with this guide, you can find out how to do it without the need to search for extra information in all corners of the internet. Let’s begin.

How do I choose an Appium version?

First things first, it should be mentioned that there are a lot of differences between 1.x and 2.x versions of Appium.

1.x versions of Appium support some useful features as automatic permission granting for iOS devices specifically. Also, it does have a server GUI, so interactions with the server are much more clear and intuitive.

While 2.x versions of Appium do not have some of the good stuff that 1.x versions do, it is the latest (as of the moment of writing this article) release of Appium, which means active support. Another advantage of 2.x versions of Appium is the plugins and drivers availability.

In this guide, we will be taking a look at how to install and set up the Appium 2.x specifically.

Installing Appium

As a prerequisite, you should install Node.js and npm package manager. This can easily be done on the official node.js website. Simply download and install the latest stable version and you’re good to go! If you don’t know whether you have a node and npm installed already, you should run the following commands in your terminal to check:

• To verify node installation, use this command node -v

• To verify npm installation, use this command npm -v

  
  

After that, you are ready to install the Appium itself, which is also done in one simple command in your terminal:  npm install -g Appium

After that, the Appium should be installed globally on your machine so you don’t have to worry about running this command in your workspace folder.

But this is not the end of the process; the next step would be to prepare the Java development kit, as well as the tools you will need for working with Android and iOS apps.

Installing JDK

You can find the latest JDK freely available on the oracle website. Download and install it. After that, you should set up the JAVA_HOME environmental variable.

Let’s take a look at how to install it on Windows:

1. Go to “Start” and type “View advanced system settings”. As a result, you should see a control panel element. Open it.
2. After that, make sure you’re on the “Advanced” tab of the opened window and press the “Environment variables” button.
3. In the “System variables” section, click the “New…” button.
4. Set “JAVA_HOME” as a variable name and the path to the JDK as a Variable value. By default, it should be ***C:\Program Files\Java\jdk2.1 ***(keep in mind which version you install, the numbers at the end could be different)

For Mac users, you can do this by executing the following command in your terminal:

• If you use bash, use:

echo export “JAVA_HOME=\$(/usr/libexec/java_home)” >> ~/.bash_profile

• If you use zsh, use:

echo export “JAVA_HOME=\$(/usr/libexec/java_home)” >> ~/.zshrc

By following these steps, you have successfully set up the JAVA_HOME environment variable, but there is still more work to do, so let’s get to it.

The next step would be installing the Android Studio. To do this, simply go to the Android Studio website, download and install it for your respective OS.

Installing Android SDK and SDK tools

Once you have Android Studio ready to go, you should install Android SDK by following these steps:

5. Open the Android Studio
6. Click “More Actions” -> SDK manager
7. Go to “Appearance and behavior” -> System settings -> Android SDK
8. Click on the checkbox near the respective Android version you need to install (Example: Android 10.0 (Q)).
9. Click the download icon that appears to the left of the Android X.X label
10. Click “Apply” at the bottom of the Android Studio window

Also, check if the Android SDK location is set up properly. It should be displayed near the top of the Android Studio window and should look like this:  C:\Users\user\AppData\Local\Android\Sdk

Lastly, go to the SDK Tools in your Android Studio and check if you have the following components installed:

• Android SDK build tools

• Android SDK platform tools

• Android SDK command-line tools

  
  

If you do not have some of those components installed, install them similarly to steps 4-6 of the Android SDK installation.

The next step would be to add an ANDROID_HOME environment variable.

Adding android_home environment variable

For Windows, the process is similar to JAVA_HOME:

11. Go to “Start” and type “View advanced system settings”. As a result, you should see a control panel element. Open it.
12. After that, make sure you’re on the “Advanced” tab of the opened window and press the “Environment variables” button.
13. In the “System variables” section, click the “New…” button.
14. Set “ANDROID_HOME” as a variable name and the path to the Android SDK as a Variable value. By default, it should match the Android SDK location that is set up in your Android studio:  C:\Users\<username>\AppData\Local\Android\Sdk

However, that is not all. We should also update the Path variable. In order to do that, find the PATH variable in the “System variables” list, click on it, and then click “Edit.” In the opened window, click “New” and add enter the path for SDK platform tools:

C:\Users\<username>\AppData\Local\Android\Sdk\platform-tools

Then, repeat this process and add SDK tools to the path variable:

C:\Users\<username>\AppData\Local\Android\Sdk\tools

Also, add the path to SDK/bin folder:

C:\Users\<username>\AppData\Local\Android\Sdk\tools\bin

Save the changes by clicking “OK”.

For mac/linux users, the first steps are similar: download and install Android Studio and the respective sdk componends.

The ANDROID_HOME variable, however, is set up from the terminal. After you’ve done the necessary steps in the Android studio window, open the terminal.

If you use bash, do the following:

15. Open .bash_profile:  nano ~/.bash_profile
16. Add the following lines to the file:

export ANDROID_HOME=$HOME/Library/Android/sdk

export PATH=$PATH:$ANDROID_HOME/platform-tools

export PATH=$PATH:$ANDROID_HOME/tools

export PATH=$PATH:$ANDROID_HOME/tools/bin

export PATH=$PATH:$ANDROID_HOME/emulator

17. Save the changes in the file and reopen your terminal

    
    

If you use zsh, the process is similar:

18. Open .zshrc:  nano ~/.zshrc
19. Add the following lines to the file:

export ANDROID_HOME=$HOME/Library/Android/sdk

export PATH=$PATH:$ANDROID_HOME/platform-tools

export PATH=$PATH:$ANDROID_HOME/tools

export PATH=$PATH:$ANDROID_HOME/tools/bin

export PATH=$PATH:$ANDROID_HOME/emulator

20. Save the changes in the file and reopen your terminal

This covers the environment variables for Android. Now, let’s take a look at how to prepare for iOS testing.

Preparations for iOS testing

Unfortunately, in order to launch an iPhone or iPad simulator, you need to have a Macbook available. But once you open it, what’s next? This guide will help you prepare to automate the iOS app tests.

The first thing you should do is install XCode. To do that, open the App Store on your Macbook, log in to the Apple account, and get the xCode. It is available for free.

After that, make sure you have command-line tools set up properly by going to Xcode -> Settings -> Locations and checking the “Command line tools” section. If you have nothing there, simply click on the list and choose “Xcode X.X.X”.

Then, check if you have all the available platforms for your app tests. To do that, go to Xcode -> Settings -> Platforms. To add a platform version, click the “+” button at the bottom left of the window, select “iOS,” and download the package for the needed iOS version Simulator.

With that, you should have your Simulators ready for iOS testing. The next step would be installing the drivers for iOS and Android automation.

Installing xcuitest and uiautomator2 drivers

Installing those drivers is also simple. To do that, open your terminal and run the following commands:

For xcuitest:  appium driver install xcuitest

For uiatomator2:  appium driver install uiatomator2

It should also be noted, that sometimes, the installation could crash depending on your npm version. If you have any issues while running those commands, the first thing you should try is downgrading your npm version to around 6.0. Now that you have the environment and drivers set up, we can get around to installing the Appium Inspector.

Installing Appium Inspector

To be able to write your tests, you’re going to need to obtain selectors for the elements of your app. For that, we have to install an Appium Inspector. It can be found on the Appium Inspector Releases GitHub page. Download and install it for your respective OS.

Once you open the Appium inspector, make sure you have “/wd/hub/” text in the “Remote path” input field.

Next, we will have a look at how to open your Simulator in your Inspector to get the elements. We should start by launching the Appium server.

Starting the Appium server

To start the Appium server. To do that, open the terminal, and run the following command:  appium –base-path /wd/hub/

If you have done everything correctly, you’re going to see in your terminal: “Appium REST http interface listener started on http://0.0.0.0:4723/wd/hub” as well as “Available drivers:  

• xcuitest  
• uiatumator2”

It means that the server has started successfully, and the drivers are installed and usable. Leave the Appium server running in the background, and do not close the terminal. If you have any issues with the Appium launch, now is the time to troubleshoot them.

Troubleshooting Appium installation

In order to check what’s wrong, you can use a helpful tool called appium-doctor. Install it using the following npm command in your terminal: npm install appium-doctor -g

After that, to check the Appium status simply execute this command in your terminal:

appium-doctor

This should give you an idea of which components are still missing on your machine. In any case, after you’ve taken care of them, it’s time to go back to the Inspector and set the Appium capabilities.

Setting the Appium capabilities

In order for your Inspector to know which Simulator to check, you should set the capabilities. Go to the Desired capabilities and click the “+” button to add a new one. The core capabilities are the following:

• appium:deviceName – should be the same as the name of your Simulator. For example: “iPhone 14 Pro” or “Pixel 6”
• appium:platformName – should be “iOS” or “Android”
• appium:platformVersion – should correspond to the iOS or Android version of the Simulator (Example: “16.0” for the iPhone on the 16.0 version of iOS or “13” for Android with OS version 13)
• appium:automationName – should be “XCUITest” or “UiAutomator2” for iOS and Android devices respectively

These are the core capabilities with which you will be able to connect to your Simulator via Appium Inspector. Finally, you have set up Appium and the necessary things for it and created your first automated test, but how do you run it? In order to do that, we will have to set up a wdio project.

Setting up the wdio project

Starting a wdio project is not complicated at all. In order to do that, just execute the following command in the terminal, make sure to do it in the directory where you want your project to be located. After you’ve changed directories in the terminal to the folder of your choice, execute the following command:  npm init wdio@latest

After doing that and following the instructions given in the installation process, the next thing to do would be to set up the wdio config file.

Setting up the wdio config

If you need to test the app on both iOS and Android, you’re going to need two different configs. Let’s name the iOS config “wdio.ios.conf.js” and the Android config “wdio.android.conf.js.” They will be mostly similar, but the key difference will be the capabilities defined in the config. Since you will not need an Appium Inspector to run the tests, the capabilities for your devices are defined here.

Here is an example of how the wdio.android.conf.js file should look like:

path: ‘/wd/hub/’,  

    runner: ‘local’,  

    specs: [‘./path/to/specs/*.js’],  

    maxInstances: 1,  

    capabilities: [  

        {  

            ‘appium:platformName’: ‘Android’,  

            ‘appium:platformVersion’: ‘13’,  

            ‘appium:automationName’: ‘UiAutomator2’,  

            ‘appium:app’: ‘./path/to/your/application/app.apk’,  

        },      

        ],  

    port: 4724,     

    services: [  

        [‘appium’,  

            {  

                args: {  

                    relaxedSecurity: true,  

                    basePath: ‘/wd/hub’,  

                    address: ‘localhost’,  

                },  

                command: ‘appium’  

            }  

        ]  

    ],  

    logLevel: ‘debug’,  

    bail: 0,  

    waitforTimeout: 15000,  

    waitForInterval: 200,  

    connectionRetryTimeout: 90000,  

    connectionRetryCount: 3,  

    framework: ‘mocha’,  

    mochaOpts: {  

        ui: ‘bdd’,  

        timeout: 120000  

    },

The specs config setting should contain the path to your specs, while the appium:app capability should contain the path to the application for which the tests are written. The app capability should point to the .apk or .app file for Android or iOS, respectively. You can find more configuration capabilities on the official webdriverIO website. Ok, now you have some tests written and config set up, but how do you run the tests?

Running the tests

In order to run the tests, make sure the config has the correct path to the app and the test specs set up. After which, make sure your Appium server terminal instance is closed (or a different port is specified in the wdio.conf.js file); also, check that your Simulator device is open. Then, in the terminal, run the following command:  npx wdio run wdio. Android.conf,js

This is an example of a command that will run your Android tests. Make sure the name is corresponding to your .conf.js file name. If you want to run the iOS tests using this example, then use the following command:  npx wdio run wdio.ios.conf,js

But if you do not need to run all the tests at once, you can also use the following command:

npx wdio run wdio. Android.conf,js –spec specName.spec.js

This command will only run the tests defined in the specName.spec.js file.

In conclusion, you now have the knowledge on how to install Appium and all the necessary things for you to start your journey of mobile testing. Also, here are some useful links to help you figure out the Appium and Wdio commands to write the tests themselves:

• Appium documentation
• Wdio documentation