getting-started-with-mobile-visualtesting

This project contains example Appium Java tests that use the Applitools Eyes Visual AI service and the Eyes Appium Java SDK to perform visual UI tests on an example native mobile Android application.

If you want example visual UI tests for a browser-based web application, try Anand Bagmar's getting-started-with-visualtesting repo instead.

Setup

Once you've pulled this project, you'll need to install the Appium service on your system, and add the Applitools Eyes Appium SDK to the project using Apache Maven.

Build the project

Most IDEs will detect the pom.xml file in this project's root directory and recognize it as a Maven project when you first open it and/or add it to a workspace. If you've opened the project in the Eclipse IDE or Jet Brains IDEA, it should download all the dependency JARs it needs over the Internet from the Maven Central repository and compile the project automatically.

Or run this command from a terminal prompt in the project root directory to install all the projects dependencies and compile its source code using the Maven command-line tool.

./mvnw compile

Note: the above command will not run the tests.

Install Appium and related drivers & plugins

The NPM package manager can install the Appium service package and all of its related dependencies and utilities for you.

Run this command from a terminal prompt in the project root directory where the package.json file is stored.

npm install

Install and configure Android Studio

Installation and setup instructions for Android Studio here.

Usage

You will need to configure the Applitools Eyes Appium SDK, and launch an Android device emulator on your local system with the example application installed before you run the example tests in this project.

If you're testing your application using a mobile device grid, you should already know how to connect an Appium test to your test device. The instructions in this document describe how to connect the tests to an emulator running on your computer.

Note: whether you plan to test the example application using a local emulator or a remote device, you will still need to configure the Eyes Appium SDK as described below.

Set your APPLITOOLS_API_KEY

First, retrieve your API key for your user account from the Eyes Dashboard UI. The Eyes Appium SDK will use this value as an authentication token to upload visual UI checks to your Eyes test results dashboard.

There are two ways to provide your Applitools API key to the Eyes SDK.

Store it the APPLITOOLS_API_KEY environment variable or eyes.api_key property. The Eyes SDK will read the value from there automatically, and you do not need to set it explicitly in your test code.
You can hard-code your API key in the test source code by replacing line 105 of the io.samples.Hooks.java source file

eyes.setApiKey(System.getenv("APPLITOOLS_API_KEY"));

with

eyes.setApiKey("<YOUR_API_KEY_GOES_HERE>");

Note: Your Applitools API key is a secret value. The tests you run will use your API key as an authentication token to connect to the Eyes Service, so treat it like a password and do not share it with anyone.

If you have hard-coded your API key in the example test code, do not to push the source code file that includes your secret API key to a public GitHub repo!

Start an Android device emulator

Create an Android Virtual Device in Android Studio.

Run an emulator in Andriod Studio.

Install the example application

This project's sampleApps directory contains an APK file for the example Android Calculator native mobile application.

To install the app on your emulated Android device, select the AndroidCalculator.apk file and drag it onto the emulated device's main screen. Once you drop that file onto the emulator, you should see a new icon named Calculator appear among the other Android application icons installed on the device.

You don't need to start, nor launch the example app within the emulator before running your first test. The tests will automatically install, start and stop the example app as needed.

Start the Appium service

The tests will automatically start an Appium server before running the first test method, and stop the Appium server after the last test method in each example test class.

You do not need to start the Appium server yourself before launching your first test.

Launch the JUnit tests

The easiest way to run a single example JUnit test is to launch it from within your IDE. For example you can run the test classes from within the Eclipse IDE, by right-clicking on one of the test source class files and choosing Run As -> JUnit Test from the context pop-up menu.

You can also launch the tests from a terminal command line prompt using the Maven test goal by executing the following command.

./gradlew clean test --tests <test_name>

Example Test Source Files

Android

CalculatorTest.java - A basic Appium test, without Applitools Eyes
```
./gradlew clean test --tests CalculatorTest
```
CalculatorEyesTest.java - A basic Appium test, with Applitools Eyes
```
./gradlew clean test --tests CalculatorEyesTest
```
CalculatorEyesNMLTest.java - A basic appium test with Applitools Eyes and uses the Native Mobile Library and MultiViewPort capability of Applitools for a native iOS app
```
./gradlew clean test --tests CalculatorEyesNMLTest
```

iOS

WebiOSHelloWorldTest.java - A basic appium test without Applitools Eyes to test a web application (mobile-web) using a safari browser in a iOS device,
```
./gradlew clean test --tests WebiOSHelloWorldTest
```
WebiOSHelloWorldEyesTest.java - A basic appium test with Applitools Eyes to test a web application (mobile-web) using a safari browser in a iOS device,
```
./gradlew clean test --tests WebiOSHelloWorldEyesTest
```
AppiumNativeiOSHelloWorldTest.java - A basic appium test without Applitools Eyes for a native iOS app
```
./gradlew clean test --tests AppiumNativeiOSHelloWorldTest
```
AppiumNativeiOSHelloWorldEyesTest.java - A basic appium test with Applitools Eyes for a native iOS app
```
./gradlew clean test --tests AppiumNativeiOSHelloWorldEyesTest
```
- AppiumNativeiOSHelloWorldEyesNMLTest.java - A basic appium test with Applitools Eyes and uses the Native Mobile Library and MultiViewPort capability of Applitools for a native iOS app
```
./gradlew clean test --tests AppiumNativeiOSHelloWorldEyesNMLTest
```

anandbagmar / getting-started-with-mobile-visualtesting