ios.md

Nightwatch-Extra guide for iOS app test

Pre-requisites

1. install appium (follow steps from here)
2. install xcode and correct iOS simulator versions for your test.

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

"appiummweb": {
    "desiredCapabilities": {
        "browserName": "safari",
        "appiumVersion": "1.6.3",
        "automationName": "xcuitest",
        "platformName": "iOS",
        "platformVersion": "9.3",
        "deviceName": "iPhone 6",
        "waitForAppScript": "true"
    },
    "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 iOS simulator version you installed
3. deviceName has to match the iOS simulator type you installed

For native app test

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

"appiumapp": {
    "skip_testcases_on_fail": true,
    "desiredCapabilities": {
        "app": "${PATH_TO_YOUR_LOCAL_.APP_APP}",
        "appiumVersion": "1.6.3",
        "automationName": "xcuitest",
        "platformName": "iOS",
        "platformVersion": "9.3",
        "deviceName": "iPhone 6",
        "sendKeyStrategy": "setValue",
        "waitForAppScript": "true"
    },
    "selenium": {
        "start_process": false
    },
    "appium": {
        "start_process": true,
        "fullReset": true
    }
}

Notice that

1. platformVersion has to match the iOS simulator version you installed
2. deviceName has to match the iOS simulator type 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.

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 applying 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
clearMobileElValue(using, selector, callback)	clearMobileElValue("accessibility id", "mybutton")	clear text 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
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)
swipeMobileElToEl(using, selector, using2, selector2, callback)	swipeMobileElToEl("accessibility id", "answer", "accessibility id", "question")	swipe screen starting from an element with given selector to another element with given selector
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	Description
mobileElAttrContains(using, selector, attribute, expected)	mobileElAttrContains("accessibility id", "submit", "label", "Add a Card")	no nightwatch equivalent
mobileElContainsText(using, selector, expected)	mobileElContainsText("accessibility id", "submit", "Add a Card")	Only works with react-native TextInput or XCUIElementTypeTextField