NOTE: This boilerplate is for Webdriver V5, if you need a boilerplate for V4 please click here

Boilerplate project to run Appium tests together with WebdriverIO for:

• iOS/Android Native Apps
• iOS/Android Hybrid Apps

This boilerplate uses the WebdriverIO native demo app which can be found here. The releases can be found and downloaded here. Before running tests, please create a ./apps directory, download the app and move the zip files into that directory

Note:

Based on

This boilerplate is currently based on:

• WebdriverIO: 5.12.#
• Appium: 1.14.#

Quick start

Choose one of the following options:

1. Clone the git repo — git clone https://github.com/webdriverio/appium-boilerplate.git

2. Then copy the files to your project directory (all files in /tests and the wdio.conf-files in the config-folder)

3. Merge project dev dependencies with your projects dev dependencies in your package.json

4. merge the scripts to your package.json scripts

5. copy the apps down to your project

6. Run the tests for iOS with npm run ios.app and for Android with npm run android.app

7. edit the following files

appium-boilerplate/config/saucelabs/wdio.android.rdc.app.conf.js appium-boilerplate/config/saucelabs/wdio.ios.rdc.app.conf.js

where the line says testobject_app_name be sure to name it to the be actual name of the project in TestObjects, below is an example

testobject_app_name: 'ian-wdio-demo-app',

Config

This boilerplate uses a specific config for iOS and Android, see configs and are based on wdio.shared.conf.js. This shared config holds all the defaults so the iOS and Android configs only need to hold the capabilities and specs that are needed for running on iOS and or Android (app or browser).

NEW: The new @wdio/appium-service is now also integrated in this boilerplate so you don't need to start an Appium server yourself, WebdriverIO will do that for you.

Since we do not have Appium installed as part of this package, this has been configured to use the global Appium installation. This is configured in wdio.shared.conf.js

appium: {
    command : 'appium'
},

Locator strategy for native apps

The locator strategy for this boilerplate is to use accessibilityID's, see also the WebdriverIO docs or this newsletter on AppiumPro. accessibilityID's make it easy to script once and run on iOS and Android because most of the apps already have some accessibilityID's.

If accessibilityID's can't be used and for example only XPATH is only available then the following setup could be used to make cross-platform selectors

const SELECTORS = {
    WEB_VIEW_SCREEN: browser.isAndroid
        ? '*//android.webkit.WebView'
        : '*//XCUIElementTypeWebView',
};

Cloud vendors

Sauce Labs Real Device Cloud

This boilerplate now also provides a setup for testing with the Real Device Cloud (RDC) of Sauce Labs. Please check the SauceLabs-folder to see the setup for iOS and Android.

With the latest version of WebdriverIO (5.4.13 and higher) the iOS and Android config holds:

• automatic US or EU RDC cloud selection by providing a region in the config, see the iOS and the Android configs
• automatic update of the teststatus in the RDC cloud without using a customer script

Make sure you install the latest version of the @wdio/sauce-service with

$ npm install --save-dev @wdio/sauce-service

and add services: ['sauce'], to the config. If no region is provided it will automatically default to the US-RDC cloud. If you provide region: 'us' or region: 'eu' it will connect to the US or the EU RDC cloud

There are 2 scripts that can be used, see the package.json, to execute the tests in the cloud:

// For iOS
$ npm run ios.sauce.rdc.app

// For Android
$ npm run android.sauce.rdc.app

FAQ

See FAQ

Tips and Tricks

See Tips and Tricks