Latest commit b555578 Jul 6, 2018

README.md

Appium Sample in Java

This folder includes sample Appium tests using Java for Android and iOS, which can be run in Bitbar Cloud.

This example can be run either using client side execution or server side execution. To find more information about these possibilities, visit http://docs.bitbar.com/testing/appium/

Client Side Test Execution

Prerequisites

  1. Install Java

    • Currently the example project is targeting Java 1.7. To change that, modify the target and source field in pom.xml
    <plugin>
    	<groupId>org.apache.maven.plugins</groupId>
    	<artifactId>maven-compiler-plugin</artifactId>
    	<version>3.6.0</version>
    	<configuration>
    		<source>1.7</source>
    		<target>1.7</target>
    	</configuration>
    </plugin>
    
  2. Install Maven

Android

Download Sample Application BitbarSampleApp.apk

Run the following command in the root directory of the project:

mvn clean test \
-Dtest=AndroidAppiumExampleTest \
-DexecutionType=clientside \
-DapiKey=<your_bitbar_apiKey> \
-DapplicationPath=</path/to/BitbarSampleApp.apk>

in which

  • <your_bitbar_apiKey> is your apiKey to Bitbar cloud. The apiKey is available under 'My account' in Bitbar cloud.
  • </path/to/BitbarSampleApp.apk> is the path to the downloaded sample application

iOS

Download Sample Application BitbarIOSSample.ipa

Run the following command in the root directory of the project:

mvn clean test \
-Dtest=IosAppiumExampleTest \
-DexecutionType=clientside \
-DapiKey=<your_bitbar_apiKey> \
-DapplicationPath=</path/to/BitbarIOSSample.ipa>

in which

  • <your_bitbar_apiKey> is your apiKey. The apiKey is available under 'My account' in Bitbar Cloud.
  • </path/to/BitbarIOSSample.ipa> is the path to the downloaded sample application

Notes

applicationPath-argument

The applicationPath-argument is only required if the application has not yet been uploaded to Bitbar cloud project. When the applicationPath-argument is provided, the application will be automatically uploaded to Bitbar cloud before the actual test execution starts. If the application has already been uploaded, you can omit the parameter. In this case Bitbar cloud will use the latest application that has been uploaded.

Upload Test Results

When using Client Side test execution, the test results have to be uploaded to Bitbar in order for it to correctly visualize the test run's success and test cases that have been run.

OSX, Linux and Windows with Cygwin

On OSX, Linux and Windows machines with Cygwin this process can be automated by running the run_client_side_test_and_export_results.sh script. When this script is used, it replaces the "mvn clean test" part of the test execution command. For example for android you could run it as follows:

./run_client_side_test_and_export_results.sh \
-Dtest=AndroidAppiumExampleTest \
-DexecutionType=clientside \
-DapiKey=<your_bitbar_apiKey> \
-DapplicationPath=</path/to/BitbarSampleApp.apk>

Windows

On Windows machines not running Cygwin this process can be automated by running the windows_client_side_test_and_export_results.bat script. Curl has to be installed and in the Path in order for the .bat script to work.

windows_client_side_test_and_export_results.bat ^
-Dtest=AndroidAppiumExampleTest ^
-DexecutionType=clientside ^
-DapiKey=<your_bitbar_apiKey> ^
-DapplicationPath=</path/to/BitbarSampleApp.apk>

Server Side Test Execution

Create a zip file containing the project, which will be uploaded to Bitbar Cloud.

  • On OSX/Linux machines you can just run the following command at the project's root directory:

    ./zip_project.sh This creates a zip package called: server_side_test_package.zip

  • You can also manually zip the project's sources. You have to include at least the following files in the zip package. Note that these files have to be at the root of the zip file, i.e. not inside any additional directory.

    • run-tests.sh
    • pom.xml
    • src/

Project Structure

Test Cases

This is where the (Test)Magic happens. The test logic of the example test cases is located in:

  • Android: src/test/java/com/testdroid/appium/android/sample/AndroidAppiumExampleTest.java

  • iOS: src/test/java/com/testdroid/appium/ios/sample/IosAppiumExampleTest.java

These are the files you want to edit when testing your own application based on this template.

Session initialization

The logic related to setting up the test session is located in:

  • src/test/java/com/testdroid/appium/BaseTest.java

This functionality is inherited by the test cases as follows:

  • Android: BaseTest.java --> BaseAndroidTest.java --> AndroidAppiumExampleTest.java
  • iOS: BaseTest.java --> BaseIOSTest.java --> IosAppiumExampleTest.java

Most likely you won't have to edit these files at all.

Desired Capabilities

The desired capabilities are fetched from a properties-file. The properties-files are located in src/test/resources/ and are specific to the test execution type and OS version that is under test:

  • Android Server Side: desiredCapabilities.android.serverside.properties
  • Android Client Side: desiredCapabilities.android.clientside.properties
  • iOS Server Side: desiredCapabilities.ios.serverside.properties
  • iOS Client Side: desiredCapabilities.ios.clientside.properties

The properties-files are in the following format:

<desired_capability_name>=<desired_capability_value>

The desired capabilities can be divided to Appium-specific desired capabilities (such as platformName and deviceName) and Bitbar-specific desired capabilities (such as testdroid_device or testdroid_project).

The Bitbar-specific desired capabilities have to only be defined for Client Side Test Execution.

For more information about Bitbar specific capabilites, please refer to http://docs.bitbar.com/testing/appium/desired-caps/

Helpful Resources