android.md

Nightwatch-Extra guide for android app test

Pre-requisites

1. install Android Studio (follow steps from here).
2. setup AVD and create the emulator will be used for testing.
3. make sure emulator in use has the latest chrome browser. if now, follow here to install latest chrome apk

How to usage

1. Create test entry in nightwatch.json

For mweb test

In order to run test in appium locally, you can start with adding following code block into nightwatch.json

"appiumandroidmweb": {
    "desiredCapabilities": {
        "browserName": "Chrome",
        "appiumVersion": "1.6.3",
        "platformName": "Android",
        "platformVersion": "7.0",
        "deviceName": "Pixel_API_24",
        "avd": "Pixel_API_24",
        "avdArgs": "-netfast -noaudio -no-boot-anim"
    },
    "selenium": {
        "start_process": false
    },
    "appium": {
        "start_process": true
    }
}

Notice that

1. appiumVersion has to match the appium version you installed
2. platformVersion has to match the emulator version you installed
3. avd has to match the AVD name you created
4. avdArgs is optional

For native app test

You can also use the following block as template if you want to run an iOS native app test

"appiumapp":{
    "desiredCapabilities": {
        "app": "${PATH_TO_YOUR_LOCAL_.APK_APP}",
        "appiumVersion": "1.6.4",
        "platformName": "Android",
        "platformVersion": "7.0",
        "deviceName": "Pixel_API_24"
    },
    "selenium": {
        "start_process": false
    },
    "appium": {
        "start_process": true,
        "fullReset": true
    }
}

Notice that

1. platformVersion has to match the android SDK version you installed
2. deviceName has to match the AVD you installed
3. in appium entry, you can add any parameter that appium supports to launch appium server in camel case, such as fullReset will map to --full-reset.

PLEASE NOTE:

1. If avd is present, appium will launch emulator automatically. However there might be a chance that appium will time out before the emulator is launched which will fail your test. We recommend you to launch the emulator before your test run first.

2. Config test entry

The allowed configuration for desiredCapabilities can be found here.

if appium.start_process is configured and is true, nightwatch-extra will launch appium automatically at http://${selenium_host}:${selenium_port}.

NOTE: appium is also a selenium server. so selenium.start_process and appium.start_process are mutually exclusive, meaning that you can only enable one at a time.

3. Enable appium automatic start/stop functionality

Appium automatic start/stop is enabled via nightwatch's external globals. You can follow the steps to enable them.

1. create a global.js and put it in your nightwatch.json like

{
  ...
  "globals_path": "globals.js",
  ...
}

2. in global.js, add following code. If you already have a global.js, simply put startAppium and stopAppium in corresponding places.

const startAppium = require("testarmada-nightwatch-extra/lib/appium/start");
const stopAppium = require("testarmada-nightwatch-extra/lib/appium/stop");

module.exports = {
  before: function (callback) {
    startAppium(this, this.test_settings, callback);
  },

  after: function (callback) {
    stopAppium(this, callback);
  }
};

Notice that appium automatical start/stop functions are only enabled if appium.start_process is set to true.

Command vocabulary

The mobile command/assertion set follows the same convention of their desktop counterparts (see here). But we don't recommend using nightwatch command/assertion directly in your app test because nightwatch doesn't support accessibility id. To use accessibility id as your element identifier we recommend to implement your own command/assertion in the same way as the included mobile command/assertion in nightwatch-extra.

Mobile command list

Nightwatch-extra Command	Example	Description
clickMobileEl(using, selector, callback)	clickMobileEl("accessibility id", "mybutton")	click a button with given selector
getMobileEl(using, selector, callback)	getMobileEl('xpath', '//UIAButton[@name = "Add"]')	return an element with given selector in the callback if it exists
setMobileElValue(using, selector, valueToSet, callback)	setMobileElValue("accessibility id", "search", "cereal")	set element's value to given value with given selector
getMobileElValue(using, selector, callback)	setMobileElValue("accessibility id", "search")	return element's value in the callback with given selector
hideKeyboard(callback)	hideKeyboard()	hide/dismiss keyboard
swipeMobileElTo(using, selector, x, y, callback)	swipeMobileElTo("accessibility id", "search", 0, -100)	swipe screen starting from an element with given selector to point measured by vector (x, y)
swipeScreenTo(fx, fy, tx, ty, callback)	swipeScreenTo(30, 400, 0, -100)	swipe screen starting from given coordinate (fx,fy) to point measured by vector (x, y)
DEPRECATED: waitForMobileElNotPresent(using, selector)	waitForMobileElNotPresent("accessibility id", "search")	wait for an element with given selector to be disappear

Mobile assertion list

Nightwatch-extra Assertion	Example	Nightwatch Equivalent
mobileElAttrContains(using, selector, attribute, expected)	mobileElAttrContains("accessibility id", "submit", "label", "Add a Card")	(no nightwatch equivalent)