Appium

Extends Webdriver

Appium helper extends WebriverIO helper. It supports all browser methods and also includes special methods for mobile apps testing. You can use this helper to test Web on desktop and mobile devices and mobile apps.

Appium Installation

Appium is an open source test automation framework for use with native, hybrid and mobile web apps that implements the WebDriver protocol. It allows you to run Selenium tests on mobile devices and also test native, hybrid and mobile web apps.

Download and install Appium

npm install -g appium

Launch the daemon: appium

Helper configuration

This helper should be configured in codecept.json or codecept.conf.js

Example:

{
  helpers: {
      Appium: {
          platform: "Android",
          desiredCapabilities: {
              appPackage: "com.example.android.myApp",
              appActivity: "MainActivity",
              deviceName: "OnePlus3",
              platformVersion: "6.0.1"
          }
      }
    }
}

Additional configuration params can be used from https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md

Access From Helpers

Receive a Appium client from a custom helper by accessing browser property:

let browser = this.helpers['Appium'].browser

Parameters

_switchToContext

Switch to the specified context.

Parameters

appendField

Appends text to a input field or textarea. Field is located by name, label, CSS or XPath

I.appendField('#myTextField', 'appended');

Parameters

checkOption

Selects a checkbox or radio button. Element is located by label or name or CSS or XPath.

The second parameter is a context (CSS or XPath locator) to narrow the search.

I.checkOption('#agree');
I.checkOption('I Agree to Terms and Conditions');
I.checkOption('agree', '//form');

Parameters

click

Perform a click on a link or a button, given by a locator. If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string. For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched. For images, the "alt" attribute and inner text of any parent links are searched.

The second parameter is a context (CSS or XPath locator) to narrow the search.

// simple link
I.click('Logout');
// button of form
I.click('Submit');
// CSS button
I.click('#form input[type=submit]');
// XPath
I.click('//form/*[@type=submit]');
// link in context
I.click('Logout', '#nav');
// using strict locator
I.click({css: 'nav a.login'});

Parameters

closeApp

Close the given application.

I.closeApp();

Appium: support only iOS

dontSee

Opposite to see. Checks that a text is not present on a page. Use context parameter to narrow down the search.

I.dontSee('Login'); // assume we are already logged in

Parameters

dontSeeCheckboxIsChecked

Verifies that the specified checkbox is not checked.

Parameters

dontSeeElement

Opposite to seeElement. Checks that element is not visible (or in DOM)

Parameters

dontSeeInField

Checks that value of input field or textare doesn't equal to given value Opposite to seeInField.

Parameters

fillField

Fills a text field or textarea, after clearing its value, with the given string. Field is located by name, label, CSS, or XPath.

// by label
I.fillField('Email', 'hello@world.com');
// by name
I.fillField('password', '123456');
// by CSS
I.fillField('form#login input[name=username]', 'John');
// or by strict locator
I.fillField({css: 'form#login input[name=username]'}, 'John');

Parameters

grabAllContexts

Get list of all available contexts

let contexts = await I.grabAllContexts();

Appium: support Android and iOS

grabContext

Retrieve current context

let context = await I.grabContext();

Appium: support Android and iOS

grabCurrentActivity

Get current device activity.

let activity = await I.grabCurrentActivity();

Appium: support only Android

grabNetworkConnection

Get information about the current network connection (Data/WIFI/Airplane). The actual server value will be a number. However WebdriverIO additional properties to the response object to allow easier assertions.

let con = await I.grabNetworkConnection();

Appium: support only Android

grabOrientation

Get current orientation.

let orientation = await I.grabOrientation();

Appium: support Android and iOS

grabSettings

Get all the currently specified settings.

let settings = await I.grabSettings();

Appium: support Android and iOS

grabTextFrom

Retrieves a text from an element located by CSS or XPath and returns it to test. Resumes test execution, so should be used inside async with await operator.

let pin = await I.grabTextFrom('#pin');

If multiple elements found returns an array of texts.

Parameters

grabValueFrom

Retrieves a value from a form element located by CSS or XPath and returns it to test. Resumes test execution, so should be used inside async function with await operator.

let email = await I.grabValueFrom('input[name=email]');

Parameters

hideDeviceKeyboard

Hide the keyboard.

// taps outside to hide keyboard per default
I.hideDeviceKeyboard();
I.hideDeviceKeyboard('tapOutside');

// or by pressing key
I.hideDeviceKeyboard('pressKey', 'Done');

Parameters

installApp

Install an app on device.

I.installApp('/path/to/file.apk');

Parameters

makeTouchAction

The Touch Action API provides the basis of all gestures that can be automated in Appium. At its core is the ability to chain together ad hoc individual actions, which will then be applied to an element in the application on the device. See complete documentation

I.makeTouchAction("~buttonStartWebviewCD", 'tap');

Appium: support Android and iOS

Parameters

openNotifications

Open the notifications panel on the device.

I.openNotifications();

Appium: support only Android

pullFile

Pulls a file from the device.

I.pullFile('/storage/emulated/0/DCIM/logo.png', 'my/path');
// save file to output dir
I.pullFile('/storage/emulated/0/DCIM/logo.png', output_dir);

Appium: support Android and iOS

Parameters

removeApp

Remove an app from the device.

I.removeApp('appName', 'com.example.android.apis');

Parameters

rotate

Perform a rotation gesture centered on the specified element.

I.rotate(120, 120)

See corresponding webdriverio reference.

Appium: support only iOS

Parameters

runInWeb

Execute code only in Web mode.

I.runInWeb(() => {
   I.waitForElement('#data');
   I.seeInCurrentUrl('/data');
});

Parameters

runOnAndroid

Execute code only on Android

I.runOnAndroid(() => {
   I.click('io.selendroid.testapp:id/buttonTest');
});

Additional filter can be applied by checking for capabilities. For instance, this code will be executed only on Android 6.0:

I.runOnAndroid({platformVersion: '6.0'},() => {
   // ...
});

Also capabilities can be checked by a function. In this case, code will be executed only on Android >= 6.

I.runOnAndroid((caps) => {
   // caps is current config of desiredCapabiliites
   return caps.platformVersion >= 6
},() => {
   // ...
});

Parameters

runOnIOS

Execute code only on iOS

I.runOnIOS(() => {
   I.click('//UIAApplication[1]/UIAWindow[1]/UIAButton[1]');
   I.see('Hi, IOS', '~welcome');
});

Additional filter can be applied by checking for capabilities. For instance, this code will be executed only on iPhone 5s:

I.runOnIOS({deviceName: 'iPhone 5s'},() => {
   // ...
});

Also capabilities can be checked by a function.

I.runOnAndroid((caps) => {
   // caps is current config of desiredCapabiliites
   return caps.platformVersion >= 6
},() => {
   // ...
});

Parameters

see

Checks that a page contains a visible text. Use context parameter to narrow down the search.

I.see('Welcome'); // text welcome on a page
I.see('Welcome', '.content'); // text inside .content div
I.see('Register', {css: 'form.register'}); // use strict locator

Parameters

seeAppIsInstalled

Check if an app is installed.

I.seeAppIsInstalled("com.example.android.apis");

Parameters

seeAppIsNotInstalled

Check if an app is not installed.

I.seeAppIsNotInstalled("com.example.android.apis");

Parameters

seeCheckboxIsChecked

Verifies that the specified checkbox is checked.

I.seeCheckboxIsChecked('Agree');
I.seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms
I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});

Parameters

seeCurrentActivityIs

Check current activity on an Android device.

I.seeCurrentActivityIs(".HomeScreenActivity")

Appium: support only Android

Parameters

seeDeviceIsLocked

Check whether the device is locked.

I.seeDeviceIsLocked();

Appium: support only Android

seeDeviceIsUnlocked

Check whether the device is not locked.

I.seeDeviceIsUnlocked();

Appium: support only Android

seeElement

Checks that a given Element is visible Element is located by CSS or XPath.

I.seeElement('#modal');

Parameters

seeInField

Checks that the given input field or textarea equals to given value. For fuzzy locators, fields are matched by label text, the "name" attribute, CSS, and XPath.

I.seeInField('Username', 'davert');
I.seeInField({css: 'form textarea'},'Type your comment here');
I.seeInField('form input[type=hidden]','hidden_value');
I.seeInField('#searchform input','Search');

Parameters

seeOrientationIs

Check the device orientation

I.seeOrientationIs('PORTRAIT');
I.seeOrientationIs('LANDSCAPE')

Parameters

selectOption

Selects an option in a drop-down select. Field is searched by label | name | CSS | XPath. Option is selected by visible text or by value.

I.selectOption('Choose Plan', 'Monthly'); // select by label
I.selectOption('subscription', 'Monthly'); // match option by text
I.selectOption('subscription', '0'); // or by value
I.selectOption('//form/select[@name=account]','Premium');
I.selectOption('form select[name=account]', 'Premium');
I.selectOption({css: 'form select[name=account]'}, 'Premium');

Provide an array for the second argument to select multiple options.

I.selectOption('Which OS do you use?', ['Android', 'iOS']);

Parameters

sendDeviceKeyEvent

Send a key event to the device. List of keys: https://developer.android.com/reference/android/view/KeyEvent.html

I.sendDeviceKeyEvent(3);

Parameters

setImmediateValue

Set immediate value in app.

See corresponding webdriverio reference.

Appium: support only iOS

Parameters

setNetworkConnection

Set network connection mode.

I.setNetworkConnection(0) // airplane mode off, wifi off, data off
I.setNetworkConnection(1) // airplane mode on, wifi off, data off
I.setNetworkConnection(2) // airplane mode off, wifi on, data off
I.setNetworkConnection(4) // airplane mode off, wifi off, data on
I.setNetworkConnection(6) // airplane mode off, wifi on, data on

See corresponding webdriverio reference.

Appium: support only Android

Parameters

setOrientation

Set a device orientation. Will fail, if app will not set orientation

I.setOrientation('PORTRAIT');
I.setOrientation('LANDSCAPE')

Parameters

setSettings

Update the current setting on the device

I.setSettings({cyberdelia: 'open'});

Parameters

shakeDevice

Perform a shake action on the device.

I.shakeDevice();

Appium: support only iOS

simulateTouchId

Simulate Touch ID with either valid (match == true) or invalid (match == false) fingerprint.

I.touchId(); // simulates valid fingerprint
I.touchId(true); // simulates valid fingerprint
I.touchId(false); // simulates invalid fingerprint

Appium: support only iOS TODO: not tested

Parameters

startActivity

Start an arbitrary Android activity during a session.

I.startActivity('io.selendroid.testapp', '.RegisterUserActivity');

Appium: support only Android

Parameters

swipe

Perform a swipe on the screen or an element.

let locator = "#io.selendroid.testapp:id/LinearLayout1";
I.swipe(locator, 800, 1200, 1000);

See complete reference

Parameters

swipeDown

Perform a swipe down on an element.

let locator = "#io.selendroid.testapp:id/LinearLayout1";
I.swipeDown(locator); // simple swipe
I.swipeDown(locator, 500); // set speed
I.swipeDown(locator, 1200, 1000); // set offset and speed

Parameters

swipeLeft

Perform a swipe left on an element.

let locator = "#io.selendroid.testapp:id/LinearLayout1";
I.swipeLeft(locator); // simple swipe
I.swipeLeft(locator, 500); // set speed
I.swipeLeft(locator, 1200, 1000); // set offset and speed

Parameters

swipeRight

Perform a swipe right on an element.

let locator = "#io.selendroid.testapp:id/LinearLayout1";
I.swipeRight(locator); // simple swipe
I.swipeRight(locator, 500); // set speed
I.swipeRight(locator, 1200, 1000); // set offset and speed

Parameters

swipeTo

Perform a swipe in selected direction on an element to searchable element.

I.swipeTo(
 "android.widget.CheckBox", // searchable element
 "//android.widget.ScrollView/android.widget.LinearLayout", // scroll element
  "up", // direction
   30,
   100,
   500);

Parameters

swipeUp

Perform a swipe up on an element.

let locator = "#io.selendroid.testapp:id/LinearLayout1";
I.swipeUp(locator); // simple swipe
I.swipeUp(locator, 500); // set speed
I.swipeUp(locator, 1200, 1000); // set offset and speed

Parameters

switchToNative

Switches to native context. By default switches to NATIVE_APP context unless other specified.

I.switchToNative();

// or set context explicitly
I.switchToNative('SOME_OTHER_CONTEXT');

Parameters

switchToWeb

Switches to web context. If no context is provided switches to the first detected web context

// switch to first web context
I.switchToWeb();

// or set the context explicitly
I.switchToWeb('WEBVIEW_io.selendroid.testapp');

Parameters

tap

Taps on element.

I.tap("~buttonStartWebviewCD");

Shortcut for makeTouchAction

Parameters

touchPerform

Performs a specific touch action. The action object need to contain the action name, x/y coordinates

I.touchPerform([{
    action: 'press',
    options: {
      x: 100,
      y: 200
    }
}, {action: 'release'}])

I.touchPerform([{
   action: 'tap',
   options: {
       element: '1', // json web element was queried before
       x: 10,   // x offset
       y: 20,   // y offset
       count: 1 // number of touches
   }
}]);

Appium: support Android and iOS

Parameters