mobile » Configure mobile device profile

Introduction

Nexial uses the concept of “profile” to configure your target mobile device, much like how a profile is used in aws.ses, aws.s3, aws.sqs, ssh, web, webmail, mail, etc. Using a “profile”, one configure a set of settings for a specific device target. This also means that one could create multiple profiles, each for a specific device target, and toggle amongst them as needed. Nexial extends of the idea of data-driven automation via this “profile” concept so that the corresponding script would be resilient against configuration changes cause by device target.

A profile is essentially a set of configurations with a shared prefix (aka profile name). These configurations can be defined in a datasheet or project.properties. A profile is referenced by the use(profile) command to start a mobile automation session. Consequently, the same use(profile) command should be considered as the first command to invoke when perform mobile testing, so that the appropriate device context and appium runtime is instantiated.

Configuration

Here are the common configurations for any device target: (assuming profile name as PHONE)

configuration	value	notes
PHONE.type	android or ios	(REQUIRED)
PHONE.server.url	(empty)or http://...	specify an externally managed Appium server URL. If none is specified, Nexial will start Appium server internally and terminate it when the execution is complete.
PHONE.server.logging	true or false	if true, Appium-specific logs will be created under <OUTPUT>/logs/appium.log.
PHONE.nexial.mobile.sessionTimeoutMs	(default) 300000	override System variable of the same name.
PHONE.nexial.mobile.postActionWaitMs	(default) 0	override System variable of the same name.
PHONE.nexial.mobile.explicitWaitMs	(default) 5000	override System variable of the same name.
PHONE.nexial.mobile.implicitWaitMs	(default) 0	override System variable of the same name.
PHONE.nexial.mobile.hideKeyboard	(default) true	override System variable of the same name.
PHONE.geoLocation	(Emulator only)	simulate another location via (longitude,latitude). For example 46.457398,-119.407305.

Nexial supports all the Appium Desired Capabilities. Simply prefix the capability name in question with the profile name. For example,

configuration	purpose	reference under Appium Desired Capabilities
PHONE.deviceName	The target device name	General Capabilities » deviceName
PHONE.platformVersion	Mobile OS version	General Capabilities » platformVersion
PHONE.udid	Unique Device Identifier	General Capabilities » udid
PHONE.app	Location of target app	General Capabilities » app
PHONE.orientation	(Emulator only) start application in a certain orientation	General Capabilities » orientation
PHONE.appPackage	(Android only) package of the target app	Android Only » appPackage
PHONE.appActivity	(Android only) the activity name to wait for	Android Only » appPackage

Note that some platform or driver specific capabilities contain :, which can be an issue if you use project.properties to define your device profile. In such case, be sure to “escape” the colon characters, like this:

PHONE.appium\:simulatorStartupTimeout=120000
PHONE.appium\:enableWebviewDetailsCollection=true
PHONE.appium\:maxInstances=1

---

Finding UDID

There are multiple ways to finding UDID of your target devices, emulators or simulators.

For Android devices

Use Nexial’s show-android-devices utility script to find actively connected devices and emulators.

For Windows:

cd %NEXIAL_HOME%
cd bin\mobile
show-android-devices.sh

For Linux/MacOS:

cd $NEXIAL_HOME
cd bin/mobile
./show-android-devices.sh

Here’s an example output:

The highlighted portion is the UDID for the connected device/emulator.

For iOS devices

To find the UDID of the connected device or simulator, here are a few ways:

1. To find the UDID of connected device:

   idevice_id –list
   

2. To find the UDID of running simulator:

   xcrun simctl list | grep Booted
   

       

3. Use Xcode to find the UDID (Identifier) of connected devices and simulators:
       Xcode -> Window -> Devices and Simulators -> Select Device
       
       

---

Finding appId, appPackage, appActivity or bundleId (iOS)

Approach 1: Use Nexial’s nexial-apk-manifest utility script

nexial-apk-manifest.cmd|sh

nexial-apk-manifest.cmd|sh

Nexial comes with a utility to assist in finding the appId (or appPackage) and appActivity via the corresponding .apk file (Android app). With this utility, one can find the appId for the mobile » launchApp(app) command, as well as the appPackage and appActivity for setting up a mobile profile. Here's how to run the nexial-apk-manifest utility:

On Windows:

cd %NEXIAL_HOME%
cd bin\mobile
nexial-apk-manifest.cmd -a [FULLY_QUALIFIED_PATH_TO_YOUR_APK_FILE]

On Linux/MacOS:

cd $NEXIAL_HOME
cd bin/mobile
./nexial-apk-manifest.sh -a [FULLY_QUALIFIED_PATH_TO_YOUR_APK_FILE]

Here's an example output of this utility:

Note that usually `appId` is the same as appPackage.

Approach 2: (Android only) Via Google Play Store

2 Ways to find appPackage and appActivity name of your App

Approach 3: (iOS only) Use Nexial’s show-ios-bundleid.sh utility script

To determine the bundleId for iOS apps, one can use Nexial’s show-ios-bundleid.sh script, like this:

cd $NEXIAL_HOME
cd bin/mobile
./show-ios-bundleid.sh [location of .app file]

Here’s an example output:

Note that since iOS automation is only supported on MacOS (requires Xcode), this script will work only on MacOS as well.

---

Copy files to device

For the purpose of testing, it is useful to prepare your target device or emulator with the appropriate files. For this reason, one can use the follow utility scripts to perform the file copy operation:

Copy to Android using `bin/mobile/copy-to-android.[cmd|sh]

cd %NEXIAL_HOME%
cd bin\mobile
copy-to-android.cmd C:\projects\MyProject\artifact\data\Test.pdf Downloads

Note that this utility script will copy a file from your computer to the device/emulator’s primary external storage. Primary external storage - a.k.a. /storage/self/primary/ - is the location where the media files, documents, etc. of the current user are stored. Typically, there are multiple subdirectories created under this storage location:

Common target directories to receive files are:

• DCIM
• Documents
• Download
• Movies
• Music
• Pictures

Copy to iOS using `bin/mobile/copy-to-ios.sh (on MacOS only)

cd $NEXIAL_HOME
cd bin/mobile
./copy-to-ios.sh ~/Pictures/myPix.png

Since iOS support requires MacOS, this file copy utility script will only work on MacOS. Also, at the time of this writing, only media files are supported, and they will be copied to the Photo library of the connected device.