Getting Started

Introduction

In this series, we will add an Appium layer to our Java Web Selenium framework so that we can run our tests on mobile browsers (e.g. Android and iOS).

Appium can run tests on Android on both Mac and Windows, but Appium can only run tests on iOS when using a Mac machine.  Due to this, I recommend following this blog series using a Mac.  I will however, explain in this part how to get started on Windows too in case you don’t have a Mac and only want to automate on Android using Windows.

The completed repository can be found at https://gitlab.com/testifyqa/Java-Appium-Mobile-Web-Gradle

We will use the following in our framework:

  • Selenium WebDriver
    • Selenium is a portable software-testing framework for web applications. Selenium provides a playback (formerly also recording) tool for authoring tests without the need to learn a test scripting language (Selenium IDE). It also provides a test domain-specific language (Selenese) to write tests in a number of popular programming languages, including C#, Groovy, Java, Perl, PHP, Python, Ruby and Scala. The tests can then run against most modern web browsers. Selenium deploys on Windows, Linux, and macOS platforms. It is open-source software, released under the Apache 2.0 license: web developers can download and use it without charge.
  • Cucumber
    • Cucumber is a software tool used by computer programmers for testing other software. It runs automated acceptance tests written in a behaviour-driven development style. Central to the Cucumber BDD approach is its plain language parser called Gherkin.
  • TestNG
    • TestNG is a testing framework for the Java programming language, inspired by JUnit and NUnit. The design goal of TestNG is to cover a wider range of test categories: unit, functional, end-to-end, integration, etc., with more powerful and easy-to-use functionalities. It is similar to JUnit but has extra capabilities
  • Appium
    • Appium is an open source automation tool for running scripts and testing native applications , mobile-web applications and hybrid applications on Android or iOS using a webdriver.

Pre-Requisites

Because we are testing a web application on mobile browser and for ease, before beginning this blog section, it is required to have completed our Java Web Selenium framework so that we can add the Appium layer to this.

The completed repository for the Java Web Selenium framework can be found at https://gitlab.com/testifyqa/Java-Web-Selenium-Gradle

Setting Up Appium

Appium works by sending commands from our Appium client (added to our codebase in an IDE) to an Appium server, via JSON Wire Protocol.  Appium Server then creates a mobile automation session for the client and checks against any Desired Capabilities that we have specified to then connect to our respective vendor-provided framework (e.g. Selendroid/UIAutomator for Android or XCUITest for iOS) and run our tests in a session against the appropriate mobile device/platform defined in our Desired Capabilities. Don’t worry if you don’t understand all of this now, as hopefully it will make more sense as we go through everything.

In order to set up our Appium environment, there are several things we need to do, as outlined below…

  1. Download and install Android Studio
    • Check Android installation path on Mac machine
    • Set $ANDROID_HOME environment variables path to Android SDK location and include bin folder paths in PATH variable
    • Open Android Studio and configure virtual devices/emulators
      • Open emulator and ensure it works
  2. Install Xcode
    • Validate iOS simulators
  3. Download Node.js
    • Set $NODE_HOME environment variables path
    • Set NPM environment variables path
  4. Download Appium Server from NPM (Node Package Manager)
  5. Download Appium client (Selenium which is also required, has already been added in the Java Web Selenium framework)

Let’s begin 🙂 …

Android

Download and Install Android Studio

  1. Go to https://developer.android.com/studio/ and click ‘Download Android Studio’
    • Agree to the terms and conditions and click ‘Download Android Studio for Mac’
  2. Launch the downloaded Android Studio DMG file
    • Drag and drop Android Studio into the /Applications folder, then launch Android Studio
    • Select whether you want to import previous Android Studio settings, then click ‘OK’
  3. Follow the install wizard, selecting ‘Standard’ and complete the installation of Android Studio and SDK

Set ANDROID_HOME environment variable

Mac
  1. Open up Terminal and type the following (excluding typing the $)… 
    $ nano ~/.bash_profile
  2. Add the following lines to your .bash_profile within Terminal, to set the $ANDROID_HOME environment variable as well as including the bin directory paths (e.g. for platform-tools and emulators etc.)… 
    export ANDROID_HOME=/Users/username/Library/Android/sdk

    (change to your Android SDK path)

    export PATH=$ANDROID_HOME/platform-tools:$PATH
    export PATH=$ANDROID_HOME/tools:$PATH
    export PATH=$ANDROID_SDK/emulator:$ANDROID_SDK/tools:$PATH
Windows
  1. Right-click on the Start button and select ‘System’
    • Select ‘System Info’ under the ‘Related settings’ section
    • Click ‘Advanced System Settings’ and select the ‘Advanced’ tab
    • Click ‘Environment Variables…’
  2. Under the ‘User Variable’ table, click ‘New’ to open ‘New User Variable’ dialog
    • Put ANDROID_HOME as Variable Name
    • Provide the path of the Android SDK folder for Variable Value (e.g. ‘C:\Android’ )
      • Choose a path without whitespace like the example given
Path Variables (Windows)
  1. Go to the Android SDK folder in explorer
    • Inside the SDK folder look for ‘tools’ and ‘platform-tools’ folder
  2. Go into Environment Variables again
    • Go to User Variables table again and locate the Path variable.
    • Select ‘Path’ in the User Variables table and click ‘Edit’
    • Ensure the following are listed in Path…
      • %ANDROID_HOME%
      • %ANDROID_HOME%\tools\
      • %ANDROID_HOME%\tools\bin
      • %ANDROID_HOME%\platform-tools\
  3.  Lets’s now check that we added the Android SDK environment and path variables correctly…
    • Open up a CMD Prompt
    • Enter in 
      adb
      • If you see output like below then that means the Android SDK path variable has been configured successfully… 
        C:\Users\Username>adb
Android Debug Bridge version 1.0.39
Version 0.0.1-4500957
Installed as C:\Program Files (x86)\Android\android-sdk\platform-tools\adb.exe

Configure Android Virtual Devices

We will now configure some Android emulators that we can later use with Appium to run our tests on

  1. Launch Android Studio
    • Select ‘Start a new Android Studio Project’
    • Leave all the options as they are by default in the Create New Project wizard and keep clicking ‘Next’
    • Click ‘Finish’ on the last screen of the wizard
  2. In Android Studio, advance to ‘Tools’ –> ‘AVD Manager’
  3. Click ‘Create Virtual Device’
    • Select a suitable device definition (e.g. Phone – Nexus 5X) and click ‘Next’
    • Select a suitable system image / Android OS (e.g. Oreo – API Level 27) and click ‘Next’ (usually latest is the best to choose, make sure it is compatible with Appium and download the image if necessary)
    • Give the Android Virtual Device (AVD) a suitable name (e.g. Nexus5xOreo) and click ‘Finish’
      • You can now click the ‘Play’ icon and open the virtual device if you want and play around with it (e.g. try opening Chrome browser in it or another app)
  4. From now on, you can also open up the AVD via Terminal. Open up Terminal and type in the following commands… 
    cd $ANDROID_HOME/platform-tools
    emulator -avd yourAvdName

    (replace ‘yourAvdName’ with name of the AVD you made)

iOS

Download and Install Xcode

Xcode is an integrated development environment (IDE) for macOS containing a suite of software development tools developed by Apple for developing software for macOS, iOS, watchOS, and tvOS.

Xcode should be included on macOS by default, but if it isn’t, open up the App Store on macOS, search for Xcode and click ‘Get’.

  1. Launch Xcode
  2. Advance to ‘Window’ –> ‘Devices & Simulators’
    • Select the ‘Simulators’ tab and view the list of iOS simulators available for use

Node.js & NPM (Node Package Manager)

Node.js is an open-source, cross-platform JavaScript run-time environment that executes JavaScript code outside of a browser.

NPM is a package manager for the JavaScript programming language. It is the default package manager for the JavaScript runtime environment Node.js. It consists of a command line client, also called npm, and an online database of public and paid-for private packages, called the npm registry.

Mac

Setting up Homebrew

Homebrew is a free and open-source software package management system that simplifies the installation of software on Apple’s macOS operating system. Originally written by Max Howell, the package manager has gained popularity in the Ruby on Rails community and earned praise for its extensibility.

  1. Open up Terminal and paste the following command to download and install Homebrew (if you run into any issues, consult https://docs.brew.sh/Common-Issues)… 
    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  2. Once Homebrew is installed, let’s make sure Homebrew is up to date by running the following command… 
    brew update
  3. It is also recommended to run Brew Doctor and follow any instructions to resolve any errors/warnings that the brew doctor returns… 
    brew doctor
Add Homebrew’s location to $PATH
  1. Open up Terminal and type the following (excluding typing the $)… 
    $ nano ~/.bash_profile
  2. Add the following line to your .bash_profile within Terminal, to add Homebrew’s location to $PATH… 
    export PATH="/usr/local/bin:$PATH"

Windows

Setting up Chocolatey

Chocolatey is a package manager for Windows. It is a single, unified interface designed to easily work with all aspects of managing Windows software (installers, zip archives, runtime binaries, internal and 3rd party software) using a packaging framework that understands both versioning and dependency requirements. Chocolatey packages encapsulate everything required to manage a particular piece of software into one deployment artifact by wrapping installers, executables, zips, and scripts into a compiled package file. Chocolatey packages can be used independently, but also integrate with configuration managers like SCCM, Puppet, and Chef.

  1. Search for CMD Prompt
  2. Right-click on Command Prompt and select ‘Run as administrator’
  3. Run the following command… 
    @"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
  4. Let’s now check that Chocolatey was installed successfully by checking the version number (exit and restart command prompt first if necessary)… 
    chocolatey -v

Setting up Node.js and NPM

Mac
  1. Open up Terminal and use Homebrew to install Node.js (NPM will be installed with Node)… 
    brew install node
  2. You can check that Node.js and NPM were installed successfully by checking their appropriate version numbers in Terminal… 
    node -v
    npm -v
Windows
  1. Open up an elevated Command Prompt (run as Administrator again) and use Chocolatey to install Node.js (NPM will be installed with Node)… 
    choco install nodejs.install
  2. Let’s then check that Node.js and NPM have been installed successfully by checking their version numbers. Enter each of the following in the elevated Command Prompt… 
    node -v
    npm -v

Installing Appium Server

We can now use NPM (Node Package Manager) to install Appium server globally on our system.

Normally, I like to follow best practices and install all my NPM packages locally to the project that depends on them, however with Appium Server, it is required to install it globally (or add ‘./node_modules/.bin/appium’ to PATH) if you want to be able to start it up programatically in Java using ‘AppiumDriverLocalService’.

This is OK as in a later part of this series when we add our Appium test framework to a CI/CD build server like Jenkins, we can define any NPM packages that we want to install globally in it (and of course Appium Server will be one of those). Obviously any developer working on the project will also need to install Appium Server globally on their machine.

  1. Open up Terminal (or Command Prompt) and change directory (cd) into the local project root for this project… 
    cd path/to/Project

    (change ‘path/to/Project’ to the path of your local project)

  2. Once at the project root in Terminal (or Command Prompt), let’s initialise NPM so we can create our package.json file which will list all the NPM packages we contain in / that are local to our project (we won’t actually have any because we are installing appium globally, but it’s good practice any how)… 
    npm init -y
  3. Now let’s install Appium Server globally to our system… 
    npm install -g appium
    • You can check Appium Server was successfully installed globally after, by entering into Terminal (or Command Prompt): 
      appium -v

Install Appium Client

We are now ready to add Appium to our Java Web Selenium project. All we need to do is simply add a dependency for Appium to our build.gradle file

  1. Launch IntelliJ and open up the Java Web Selenium project
  2. Open up the build.gradle file and add the following Gradle dependency for Appium (note the version number might be different when you add, check mvnrepository.com for the Appium dependency)… 
    compile group: 'io.appium', name: 'java-client', version: '6.1.0'

Congratulations, the initial environment setup for Appium is now complete. In the next section we will begin adding our Desired Capabilities for our test virtual devices and building out the framework 😀

Digiprove sealCopyright secured by Digiprove © 2018
Liked it? Take a second to support Thomas on Patreon!

Previous Article

Next Article

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.