nativescript-dev-appium

A helper package to make running E2E Appium tests in NativeScript apps easier.

Usage

Install it with:

$ npm install --save-dev nativescript-dev-appium

Install Appium locally:

$ npm install --save-dev appium

Or install appium globally (to avoid installing it for every app):

$ npm install -g appium

After installation, you should have a sample test below the e2e directory which you can rename of your choice. However, if you rename the folder you will have to specify it using --testfolder someFolderName option.

Before running the tests you will have to build your app for the platform on test or both. Navigate to your demo app folder from where you will execute the commands that follow.

$ tns build android

or

$ tns build ios

The command that will run the tests should specify the targeted platform using the runType option as shown below. This way a capabilities will be selected from the capabilities config file if none provided on driver creation (driver = nsAppium.createDriver(capabilities);).

This will excute mocha tests or you can change mocha plugin to the prefered one
$ npm run e2e -- --runType android23

or

$ npm run e2e -- --runType ios-simulator10iPhone6

Generated tests are standard Mocha tests.

Custom Appium capabilities

Custom appium capabilities must be provided by the user by adding appium.capabilities.json file to the root directory of your repo. This is a runner's requirement which comes from Appium. Default locations where the runner will search for the config file are:

my-app
├── app
├── assets
├── package.json
.
.
.
└── appium.capabilities.json

If the file structure assembles plugin repo structure like for example nativescript-plugin-seed the right location is:

my-plugin
├── demo
├── demo-angular
├── src
└── appium.capabilities.json

Thus, the configuration can be used by both apps when tested.

If you wish to use another location of the capapabilities file instead default ones, you can specify it with --capsLocation option. Remember that the path provided has to be relative to the root directory.

Notice that once custom capabilities are provided you will be able to pick any of them using the --runType option (e.g. --runType=android21). Sample content of appium.capabilities.json file could be:

{
    "android21": {
            "browserName": "",
            "appium-version": "1.6.3",
            "platformName": "Android",
            "platformVersion": "5.0",
            "deviceName": "Android Emulator",
            "noReset": false,
            "app": ""
        
    },
    "android23": {
            "browserName": "",
            "appium-version": "1.6.5",
            "platformName": "Android",
            "platformVersion": "6.0",
            "deviceName": "Android Emulator",
            "noReset": false,
            "app": ""
        
    },
    "ios-simulator10iPhone6": {
            "browserName": "",
            "appium-version": "1.6.5",
            "platformName": "iOS",
            "platformVersion": "10.0",
            "deviceName": "iPhone 6 Simulator",
            "app": ""
        
    }
}

As you can see, the app property can be left an empty string which will force the plugin to search for an app package in platforms folder. However, this search functionality depends on runType option so if you think of using it add android, ios-device, ios-simulator strings as part of your runType option which in fact is your capability key in the config file. E.g --runType=android23, --runType=ios-simulator10iPhone6. Thus, the runner will manage to look in the right location in order to search for app package.

It is important to build your app in advance as explained in Usage section, because the runner expects to provide app package to it or such to exists in the search location.

Options

Option	Description	Value
runType	Select the capabilities from your config file appium.capabilities.json	Consider using android, ios-device, ios-simulator strings as part of your runType option if you haven't provided app capability. Thus, the runner will look for app package in the right location for the current run. e.g. --runType="ios-device10iPhone6"
appLocation	Provide location of the app package to be tested. This will overwrite all provided capabilities for app	Possible values are: - app build package name (in case --sauceLab option is set it will prepend sauce-storage: in front of the app name so app has to be uploaded to Sauce Labs before execution starts) - path e.g. platforms/android/build/outputs/apk/demo.apk. Example: --appLocation=demo-debug.apk
sauceLab	Enable tests execution in Sauce Labs. As a prerequisite you will have to define SAUCE_USER and SAUCE_KEY as environment variable	e.g. --sauceLab=true
capsLocation	Change the location where appium.capabilities.json config file can be. It should be relative to the root directory	e.g. --capsLocation="/e2e-tests"

Examples:

$ npm run e2e --runType android23 --sauceLab --appLocation demo.apk --capsLocation "/e2e-tests/config"

Troubleshooting

Use the --verbose option to get error details:

$ npm run appium --runType=android --verbose

Missing features

1. Faster developer turnaround when working on an app. Find a way to use livesync and kick off Appium tests for the app that's on the device already.

Br