test-suite

2020.10

false

OUT OF SUPPORT

Test Suite User Guide

DELIVERY:

Automation Cloud Automation Cloud Public Sector Automation Suite Standalone

Last updated Jul 15, 2024

Local Devices

Overview

To set up a local device to work with the Mobile Automation activities, be it a physical device or an emulator, you need to run a local instance of Appium, and have the necessary tools to automate Android or iOS devices.

Topic sections:

Application Storage

You will need to store your mobile apps on the same machine where your Appium server is running, or upload the APK or IPA file to an URL that is anonymously accessible by the Appium server (e.g. Blob storage).

Installing applications from the Play Store or App Store is not possible, except if you manually automate these applications to install your specific application.

Android Device Configuration

To configure a local Android device, you need to prepare your environment and add it to the Mobile Device Manager.

Topics in this section:

Preparing Android Environment

Prepare and configure your environment.

Download and install Node.js.
Open Node.js command prompt and run the following command to install Appium:

npm install -g appium

For more information on Appium configuration, see Appium Getting Started.
In Windows, navigate to Advanced system settings > Advanced > Environment Variables
Under System variables click New and configure the following variables:

a. ANDROID_HOME variable.

Variable name: ANDROID_HOME Variable value: C:\Users\Username\AppData\Local\Android\Sdk Note: The Username part, inside the Variable Value path, must be replaced with the actual name of the user operating on the machine.

b. JAVA_HOME variable. You need to have Java already installed to configure this variable. You can download Java through a zip file here.

Variable name: JAVA_HOME.

Variable value: the path where the JDK is located on your machine. For example: C:\Program Files\Java\jdk8.

Important: If Java is updated automatically, you need to manually configure this variable with the updated path.

c. Click Ok to confirm.

Edit the Path variable for your user to include Android Debug Bridge (ADB):

a. Click New and add the following value:

%ANDROID_HOME%\platform-tools

b. Click Ok to confirm.
Click Ok to set the variable.

Starting Appium Server

Before starting any application on your device, you need to start running an Appium server on your machine. Open the command prompt and run Appium with the following parameters:

appium -p 10001 --relaxed-security --allow-insecure chromedriver_autodownload

Note:

If the auto-download fails, you can point to an already downloaded chromedriver.exe, by concatenating the following command:

--chromedriver-executable "path_to_chromedriver"

To get help with your Appium debuggingg, run the following command:

appium-doctor

To kill Appium, use the ctrl + c command.

Creating Android Emulator

Create your Android emulators using Android Studio.

Download and install Android Studio.
Open Android Studio.
Click Configure and select SDK Manager from the dropdown.
Uncheck Hide Obsolete Packages and make sure that Android SDK Tools (Obsolete) is selected.
Click Apply and then Ok to close.
Navigate to Configure > AVD Manager to configure a virtual device. For more information, see Create and manage virtual devices.
Update your device's Google apps.

Enabling Web and Hybrid Automation With WebDriver

Enable WebView debugging.

If Appium doesn't autodetect the Chrome or the WebView version on your Android, choose one of the options below:

Use the --allow-insecure chromedriver_autodownload command. This enables Appium to automatically detect and download the ChromeDriver version that corresponds to your environment.
Manually specify and download the WebDriver for Chrome:
2.1. Open your device in Android Studio.

2.2. Navigate to Settings > Apps & notifications.

2.3 Click See all apps.

2.4. Click the vertical ellipsis button and select Show system from the dropdown.

2.5. Use the search function to look for Android System WebView.

2.6. Open the app and go to Advanced.

2.7. Copy the version number at the bottom of the screen.

2.8. Download WebDriver for Chrome and consider the following:
- Select the version that corresponds to the Android System Webview version from the previous step, and extract it to a folder.
- You are looking for an exact match for the version (major.minor.patch.revision).
- In case an exact match isn't available, use the latest major version of ChromeDriver that matches the major version of the Android System Webview.
- If you want to automate the Chrome app just perform the same steps from above and keep a note of the Chrome version instead.

Configuring Android Physical Device

Download and install Android Studio.
Open Android Studio.
Click Configure and select SDK Manager from the dropdown.
Uncheck Hide Obsolete Packages and make sure that Android SDK Tools (Obsolete) is selected.
Click Apply and then Ok to close.
Open a command line and run the following command to start a debugging server:

%LOCALAPPDATA%\\Android\\Sdk\\platform-tools\\adb.exe start-server
Connect your device to your machine through a cable.
Enable developer options and USB debugging on your device. For more information, see Configure on-device developer options.
On your phone, navigate to Settings > Developer Options.
Under the Networking section, open Default USB configuration and set it to Charging phone only.
Add your device to Mobile Device Manager.
Run the following command to start an Appium server:

appium -p 10001 --relaxed-security --allow-insecure chromedriver_autodownload

For additional parameters, see Starting Appium Server.

Note: Make sure to leave the Appium server connection running without any interferences. For example, if you click within the terminal, the communication is cut off, which may lead to a communication error in Mobile Device Manager.

Adding Local Android Device in Mobile Device Manager

Open MDM from Studio.
In the left navigation panel go to Devices.
Configure your device as follows:
- Name - Enter a name to identify your device in the Devices tab.
- Appium URL - Enter the localhost. For example: http://localhost:10001/wd/hub.
- Platform - Click the field to select Android from the dropdown.
- Device Name - Enter the device name. One way to see that is through Android Studio if you navigate to Configure > AVD Manager, and then go to More Actions > View Details.
- Platform Version - Add the version number of your Android OS.
- Additional Desired Capabilities (Optional) - Add specific capabilities to customize your automation session. For more information, see Appium Desired Capabilities.
- Set Geo Location (Optional) - Set your device location to test applications that use Location Services to generate location data.
(Optional) Configure logging and video recording details in the Logging tab.
(Optional) Configure your development process in the Development tab.
- Close Similar Tabs (Activated by default): Close tabs running connections with similar devices and applications.
- Wait for Page Update (Activated by default): Wait for the page source to retrieve a screenshot of each action.
Click Save & Close to add your device.

Your device is added to the Devices list. To add a local device, see Local Devices.

IOS Device Configuration

To configure a local iOS device, simulator or physical device, and automate an application, you will have to set up the Appium server on a macOS machine.

Important:

If your app artifact uses the APP extension and you want to upload the app to a public URL, you will need to create a folder named Payload, place the APP inside it, archive the Payload folder and change the extension to IPA instead of ZIP.

Additionally, ensure that the application that you are trying to automate is compiled for the target architecture (simulator or physical device).

Topics in this section:

Preparing MacOS Environment

Install Xcode.
Open a Terminal and run the following command to install Homebrew:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Run the following command to install NodeJS:

brew install node
Install Appium:

npm install -g appium
Open Xcode and allow it to install any additional components it may require. Close it once you see the splash screen.
Run the following command to start Appium:

appium --port 10001
Use Spotlight Search (⌘-Space) to open Network Utility.
Copy the IP Address for later use when you add an iOS device to MDM. This will be included in the Appium URL (e.g. http://<ipaddress>:8001/wd/hub)

Configuring IOS Physical Device

If you want to use the Mobile Automation activities with a physical iOS device, you will need an Apple Developer account.

Follow steps 1-5 from Preparing macOS Environment
Connect your physical device to your Mac.
Unlock your device and, if an alert pops up, make sure to allow the computer to access it.
Open a Terminal and run the following command:

instruments -s devices
Copy your device ID for later use, when you add your device in MDM. For example, deviceID will be added as an udid capability:

Known Devices: Username's iPhone (13.5.1) (<deviceID>)
Sign in to your Apple Developer account and go to Membership.
Copy your Team ID for later use, when you add your device in MDM. Your Team ID will have to be added to the device capabilities with the name xcodeOrgId.
Open Xcode and navigate to Preferences > Accounts.
Add your Apple Developer Account.

Adding Local IOS Device in Mobile Device Manager

Open Mobile Device Manager from Studio.
In the left navigation panel go to Devices.
Configure your device as follows:
- Name - Enter a name to identify your device in the Devices tab.
- Appium URL - Enter the localhost. For example: http://<ipaddress>:8001/wd/hub.
- Platform - Click the field to select iOS from the dropdown.
- Device Name - Enter the device name.
- Additional Desired Capabilities(Physical Devices) - Add the udid and xcodeOrgId. For more information, see Configuring iOS Physical Device
- Set Geo Location (Optional) - Set your device location to test applications that use Location Services to generate location data.
(Optional) Configure logging and video recording details in the Logging tab.
(Optional) Configure your development process in the Development tab.
- Close Similar Tabs (Activated by default): Close tabs running connections with similar devices and applications.
- Wait for Page Update (Activated by default): Wait for the page source to retrieve a screenshot of each action.
Click Save & Close to add your device.

Your device is added to the Devices list. To add a local device, see Local Devices.

If you cannot start your device, see Troubleshooting: Physical device fails to start.