Repository files navigation

A package to help with writing and executing e2eAppium tests.

• Features
• Requirеments
• Setup
  • Structure
  • Files Preview
• Usage
• Blogs
• Demos
• Videos
• Custom Appium Capabilities
• Options
• Troubleshooting
• Common Problems
• Missing Features
• Contribute
• Get Help

1. Cross-platformlocators
2. Find strategies:findElementByText,findElementByClassName,findElementByAccessibilityId,findElementByXPath
3. Actions:tap,click,doubleTap,hold
4. Gestures:scroll,scrollTo,swipe,drag
5. Cross-platform element abstraction withexists,waitForExist,waitForNotExist,location,isDisplayed,size,text properties
6. Ability to turn on/off “Don’t keep activities” setting in the Developer options for Android
7. Direct access to driver
8. Typings
9. Async/Await
10. Open source cloud builds integration, i. e.Sauce Labs
11. Image comparison of: screen, rectangle; block out areas to ignore
12. [WIP] Ability to verify animations/transitions through video/images; please refer toframe-comparer
13. Mochawesome HTML report - including screenshots in report

Thenativescript-dev-appium plugin requires:

• latest version ofAppium
  • for correct functioning of theXCUITest driver for iOS, additional libraries are required (see theSetup section)
  • for correct functioning of themobile-devices-controller for Android emulators,telnet is required (see theSetup section)
• latest version ofXcode
• Android SDK Tools version greater than 25.3.0

Add the plugin as adevDependency to your project:

$ npm install -D nativescript-dev-appium

After completion of the installation, if your project has a dependency toTypeScript, the plugin should have added ane2e folder containing predefined configs and samples.

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

$ npm install -g appium

Install external dependencies ofXCUITest driver for iOS via:

• Homebrew:

$ brew install carthage$ brew install libimobiledevice --HEAD$ brew install ideviceinstaller$ brew install ios-webkit-debug-proxy

• NPM:

$ npm install -g ios-deploy

For detailed information on external dependencies, please, refer to theXCUITest repository.

For correct functioning of themobile-devices-controller for Android emulators,telnet is required to be available on your system.

As thetelnet was removed frommacOS High Sierra, it could be installed as follows:

$ brew install telnet

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

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

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

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 capabilities configuration using therunType option as shown below. This way a capabilities will be selected from thecapabilities configuration file.

$ npm run e2e -- --runType android25

or

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

or for local runs during development

$ npm run e2e android$ npm run e2e ios$ npm run e2e -- --device.name=/iPhone X/ --device.apiLevel=/12.1/

Generated tests are standardMocha tests.

NOTE: When using Jasmine instead of Mocha, additional npm params (likerunType) must have an equal sign (=) instead of a space.

npm run e2e -- --runType=sim.iPhoneX

2018, March 6th:Start Testing Your NativeScript Apps Properly

The official demos of thenativescript-dev-appium plugin:https://github.com/NativeScript/ns-dev-days-appium-plugin.

These tests demonstrate:

• template-hello-world-ts/e2e -nativescript-dev-appium basics: configurations, find strategies, locators, actions.
• template-hello-world-ng/e2e - the page object pattern withnativescript-dev-appium.

Tests on NativeScript Continuous Integration

NativeScript/e2e/modal-navigation - use "Don't keep activities", run background (minimize/restore) app.

nativescript-angular/e2e/renderer - use basics: locators, find strategies, assertions.

nativescript-angular/e2e/router - use basics: locators, find strategies, assertions.

nativescript-dev-webpack/demo/AngularApp - use data driven approach, compares element's images.

nativescript-dev-webpack/demo/JavaScriptApp - use data driven approach, compares element's images.

nativescript-dev-webpack/demo/TypeScriptApp - use data driven approach, compares element's images.

2018 March 6th:NativeScript Air 6 - UI Testing {N} apps with DevAppium

2017 Sept 27th:NativeScript testing with Appium @NativeScript Developer Day Europe 2017

2017 Sept 19th:Introduction to Mobile UI Test Automation @NativeScript Developer Day 2017

When installed, the plugin createse2e folder containing sample test file and configuration folderconfig where your custom capabilities reside.The existence of such capabilities is a runner's requirement which comes fromAppium. 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 examplenativescript-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 capabilities file instead default ones, you can specify it with--appiumCapsLocation 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 ofappium.capabilities.json file below. For more details regarding the Appium Capabilities readAppium 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, theapp property can be left an empty string which will force the plugin to search for an app package inplatforms folder. However, this search functionality depends onrunType option so if you think of using it addandroid,device,sim strings as part of yourrunType option which in fact is your capability key in the config file. E.g --runType android23, --runType sim.iPhone8.iOS110. 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 inUsage section, because the runner expects to provide app package to it or such to exists in the search location.

For faster testing when working on an app with livesync it would be better to use --devMode option or start a new session using --startSession option and run tests using --attachToDebug option and specify appium --port. Or simply start session with appium desktop application

Examples:

Let say that we have a script in package.json like this

 "scripts": {    "e2e": "tsc -p e2e && mocha --opts ./config/mocha.opts --recursive e2e --appiumCapsLocation ./config/appium.capabilities.json" }

Run tests in sauceLab

$ npm run e2e -- --runType android25 --sauceLab --appPath demo.apk

Run tests locally

$ npm run e2e -- --runType android25

Starting new session will console log appium server port and session id

$ node ./node_modules/.bin/ns-appium --runType android23 --startSession --port 8300

Run tests with already started session. Specify session id and server port. Default value for server port is 8300

$ npm run e2e -- --sessionId e72daf17-8db6-4500-a0cf-59a66effd6b9 --port 8300

or simply use --attachToDebug which will attached to first available session. This is not recommended when more than one session is available.

$ npm run e2e -- --attachToDebug --port 8300

Use the--verbose option to get error details:

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

1. Missing installed appium
2. Misleading appPath or capabilities location. Please make sure that the path to the app or capabilities location is correct.
3. Misleading details for device specified in appium config

We love PRs! Check out thecontributing guidelines. If you want to contribute, but you are not sure where to start - look forissues labeledhelp wanted.

Please, usegithub issues strictly forreporting bugs orrequesting features. For general questions and support, check out theNativeScript community forum or ask our experts inNativeScript community Slack channel.