nativescript-dev-appium v6.1.3

nativescript-dev-appium

A package to help with writing and executing e2e Appium tests.

• Requirеments
• Set Up
  • Structure
  • Files Preview
• Usage
• Custom Appium Capabilities
• Options
• Features
• Troubleshooting
• Common Problems
• Missing Features
• Contribute
• Get Help

Requirеments

The nativescript-dev-appium plugin requires:

• latest version of Appium
• latest version of Xcode
• Android SDK Tools version greater than 25.3.0

Set Up

Add the plugin as a devDependency to your project:

$ npm install -D nativescript-dev-appium

Then install Appium - we recommend a global installation to avoid adding it to every project you would like to test:

$ npm install -g appium

After completion of the installation, if your project has a dependency to TypeScript, the plugin should have added an e2e folder containing predefined configs and samples.

Structure

    my-app
    ├── app
    ├── e2e
        ├── configs
            ├── appium.capabilities.json
            ├── mocha.opts
        ├── sample.e2e-test.ts
        ├── setup.ts
        ├── tsconfig.json
    ├── ...
    ├── package.json
    ├── tsconfig.json

Note - To avoid any incompatibilities between the source of e2e tests (ES6) and the source of the application (ES5), we recommend to exclude the e2e folder from the application's tsconfig.json file: exclude": [ "e2e" ].

Files Preview

Note - The folders below are related to the image comparison feature:

• e2e/reports - this folder is created during test execution and stores the actual images from comparison
• e2e/resources - this folder aims to store the expected images for comparison

Usage

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.

$ npm run e2e -- --runType android25

or

$ npm run e2e -- --runType sim.iPhone8.iOS110

Generated tests are standard Mocha tests.

Custom Appium Capabilities

When installed, the plugin creates e2e folder containing sample test file and configuration folder config where your custom capabilities reside. The existence of such capabilities is a runner's requirement which comes from Appium. Additional 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 suggested location is:

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

Thus, the same configuration can be used by both apps without duplication of files.

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 android25). See sample content of appium.capabilities.json file below. For more details regarding the Appium Capabilities read Appium documentation about Desired Capabilities:

{
    "android21": {
            "browserName": "",
            "platformName": "Android",
            "platformVersion": "5.0",
            "deviceName": "Android Emulator",
            "noReset": false,
            "app": ""
        
    },
    "android25": {
            "browserName": "",
            "platformName": "Android",
            "platformVersion": "7.0",
            "deviceName": "Android Emulator",
            "noReset": false,
            "app": ""
        
    },
    "sim.iPhone8.iOS110": {
            "browserName": "",
            "platformName": "iOS",
            "platformVersion": "11.0",
            "deviceName": "iPhone 8 110",
            "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, device, sim strings as part of your runType option which in fact is your capability key in the config file. E.g --runType android23, --runType sim.10iPhone6. 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

Examples:

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

Features

1. Compare images. Block out areas to ignore in comparison.
2. Find elements findElementByText, findElementsByXPath, findElementByAccessibilityId etc...
3. Gesture support: swipe, scroll, drag, scrollTo
4. Action support: tap, click, doubleTap, hold,
5. Element characteristics: location, exists, size, isDisplayed
6. Find strategies: waitForExist, waitForExistNot
7. Direct access to webdriver and webdriverio

Troubleshooting

Use the --verbose option to get error details:

$ npm run e2e -- --runType android25 --verbose

Common Problems

1. Missing installed appium
2. Misleading appPath or capabilities location. Please make sure that the path to the app or capabilities location is correct.

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.

Contribute

We love PRs! Check out the contributing guidelines. If you want to contribute, but you are not sure where to start - look for issues labeled help wanted.

Get Help

Please, use github issues strictly for reporting bugs or requesting features. For general questions and support, check out the NativeScript community forum or ask our experts in NativeScript community Slack channel.